universalid 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e55004b7c0b0346e1186784b7962857ae5a010dc85011093703c8e616359c7a9
-  data.tar.gz: c3ed66a1d494c536851cb642c7b8d538092792ec2e4b78d6b3b4db9f3628d666
+  metadata.gz: '00684769ef0a97127ef4342a3b61ef58bba2f85a7fb1ddfe55118186f7c93662'
+  data.tar.gz: 4f871efbddfb4b580d60d556cd4ca12c8135f5331dad58bac19d3152b5066282
 SHA512:
-  metadata.gz: 8bad79ee6a4b23619b894846e9499493d37d59ee88772a86327ba5d822bbc2436df05c16b5dfbdc39e276002f0703476365a45b79590af95cd2ef7558531cbd5
-  data.tar.gz: d4a48f15ea08f0cb2f0291f74ff20202c8fd2af431f0e73ba701af178c18f3219d73bc10d8269c9360d6b2f4ffe4a1a521bcbe92ca7688bd7f208acd827ec1a8
+  metadata.gz: 3a34c1492a6b4fc39babca2e246d5055fc2212104285e43a9ec4b460441d71886e76f77ebab3afb94b4f03cc03d3615975e2e348bafcbc473d7f67632cc36de6
+  data.tar.gz: 124d30882de946bf8abf6b801b44bb471c0df1d0b262f0424cb449707a01c2635b1f97892c0972bcff12411437a16b7f4fcfb0698162feafb2a3a231ce69b719

data/README.md

@@ -2,7 +2,7 @@
   <h1 align="center">Universal ID</h1>
   <p align="center">
     <a href="http://blog.codinghorror.com/the-best-code-is-no-code-at-all/">
-      <img alt="Lines of Code" src="https://img.shields.io/badge/loc-721-47d299.svg" />
+      <img alt="Lines of Code" src="https://img.shields.io/badge/loc-750-47d299.svg" />
     </a>
     <a href="https://codeclimate.com/github/hopsoft/universalid/maintainability">
       <img src="https://api.codeclimate.com/v1/badges/567624cbe733fafc2330/maintainability" />
@@ -42,44 +42,151 @@ This innovative library transforms any Ruby object into a URL-safe string, enabl
 It leverages both [MessagePack](https://msgpack.org/) and [Brotli](https://github.com/google/brotli) _(a combo built for speed and best-in-class data compression)_.
 MessagePack + Brotli is up to 30% faster and within 2-5% compression rates compared to Protobuf. <a title="Source" href="https://g.co/bard/share/e5bdb17aee91">↗</a>
 
-## Example Use Cases
-
-- **State Preservation in Web Apps**: Maintain the state of a user's session in web applications without storing data server-side
-- **API Data Transfer**: Serialize complex data structures into a URI format for easy and efficient transfer via RESTful APIs
-- **Bookmarkable Configurations**: Allow users to bookmark configurations of a web application by embedding the state in the URL
-- **Deep Linking in Web Apps**: Create deep links that carry complex state information, allowing users to return to a specific state within an application
-- **Debugging Tools**: Serialize objects and their state for logging purposes, aiding in debugging and error tracking
-- **Shareable Reports and Views**: Encode the state of reports or customized views in web applications, making them shareable
-- **Inter-Service Communication**: Facilitate communication between different services by passing complex objects in a standardized, URL-safe format
-- **Client-Side Storage Optimization**: Reduce the need for client-side storage by keeping serialized state in URLs or Cookies
-- **Versioning Serialized Objects**: Enable versioning of serialized objects in URLs, allowing users to access different states or versions of data
-- **Data Export/Import**: Simplify the export and import process of complex objects between different environments or systems by using URI-encoded data
-
-This is just a fraction of what's possible with Universal ID. It's an invaluable tool for a range of development needs. API design, data management, user experience, and more. **Endless possibilities!**
-
 <!-- Tocer[start]: Auto-generated, don't remove. -->
 
 ## Table of Contents
 
+  - [Example Use Cases](#example-use-cases)
   - [Supported Data Types](#supported-data-types)
     - [Scalars](#scalars)
     - [Composites](#composites)
+    - [Custom Types](#custom-types)
     - [Contributed Types](#contributed-types)
-    - [ActiveRecord](#activerecord)
-      - [Why Universal ID with ActiveRecord?](#why-universal-id-with-activerecord)
-    - [Custom Datatypes](#custom-datatypes)
   - [Settings and Prepack Options](#settings-and-prepack-options)
   - [Advanced ActiveRecord](#advanced-activerecord)
   - [ActiveRecord::Relation Support](#activerecordrelation-support)
   - [SignedGlobalID](#signedglobalid)
+  - [Fingerprinting (Implicit Versioning)](#fingerprinting-implicit-versioning)
   - [Performance and Benchmarks](#performance-and-benchmarks)
   - [Sponsors](#sponsors)
   - [License](#license)
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
-> :rocket: **Ready to Dive In?**: All the code examples below can be tested on your local machine. Simply clone the repo and run `bin/console` to begin exploring. Don't forget to execute `bundle` first to ensure all dependencies are up to date. Happy coding!
+## Example Use Cases
+
+Universal ID's powerful serialization capabilities unlock a myriad of possibilities across various domains.
+Here are a few possibilities.
+
+- **State Management for Web Applications**:
+  Facilitate seamless user experiences in web applications by preserving and transferring UI states, even across different sessions.
+
+- **Data Serialization for Distributed Systems**:
+  Enable efficient communication in distributed systems by serializing complex data structures for network transmission.
+
+- **Configuration Settings for Software Applications**:
+  Store and manage configuration settings for software applications, allowing easy transfer and versioning of settings across installations.
+
+- **Session Continuity in Cloud Services**:
+  Ensure continuity of user sessions in cloud-based applications, enabling users to pick up their work exactly where they left off, regardless of the device or location.
+
+- **Audit Logging for Complex Transactions**:
+  Record detailed states of complex transactions in audit logs, providing a comprehensive and reversible record of actions for compliance and analysis.
+
+- **Machine-to-Machine Communication**:
+  Standardize data formats for machine-to-machine communication, facilitating interoperability and data exchange in IoT and other automated systems.
+
+These use cases demonstrate the versatility and power of Universal ID in various application and business scenarios, offering solutions that enhance efficiency, user experience, and system reliability.
+
+<details>
+  <summary><b>See More Use Cases</b>... ▾</summary>
+  <p></p>
+
+  Harnessing the capabilities of this advanced low-level tool in your libraries and applications might initially seem daunting.
+  To assist you in unlocking its full potential, here are some additional suggestions to help you get started.
+
+  - **API Response Caching**
+    Cache complex API responses as serialized strings, allowing for efficient storage and quick retrieval.
+
+  - **Asset Management in Enterprises**
+    Serialize asset information, including status and location, for efficient tracking and management.
+
+  - **Audit Logging for Financial Transactions**
+    Serialize transaction states for audit trails in financial applications, providing detailed and reversible records for compliance.
+
+  - **Automated Testing of Web Applications**
+    Serialize application states to reproduce and test various scenarios automatically.
+
+  - **Backup and Restore of Application States**
+    Create snapshots of application states that can be backed up and later restored.
+
+  - **Configuration Management in DevOps**
+    Serialize configuration settings for software deployments, enabling easy versioning and rollback.
 
+  - **Content Management Systems (CMS)**
+    Serialize page or post states in CMS, enabling advanced versioning and preview functionalities.
+
+  - **Customer Support Tools**
+    Serialize user issues and their context, helping support teams to quickly understand and resolve customer problems.
+
+  - **Data Migration Between Databases**
+    Serialize entire database records for easy transfer between different database systems or formats.
+
+  - **Educational Platforms**
+    Serialize user progress and states in educational platforms, allowing students to pause and resume their learning activities.
+
+  - **E-commerce Cart Persistence**
+    Serialize shopping cart contents, enabling users to return to a filled cart even after their session expires.
+
+  - **Energy Management Systems**
+    Serialize energy usage data from various sensors for analysis and monitoring.
+
+  - **Environmental Monitoring Systems**
+    Serialize sensor data from environmental monitoring systems for analysis and historical record keeping.
+
+  - **Event Sourcing in Applications**
+    Use serialized states for event sourcing, maintaining an immutable log of state changes over time.
+
+  - **Gaming State Preservation**
+    Store game states as serialized strings, allowing players to resume games exactly where they left off.
+
+  - **Healthcare Data Exchange**
+    Securely transfer patient data between different healthcare systems while maintaining the integrity of complex data structures.
+
+  - **IoT Device State Management**
+    Serialize the state of IoT devices for efficient transmission over networks, aiding in remote monitoring and control.
+
+  - **Legal Document Management**
+    Serialize versions of legal documents, maintaining a trail of edits and changes for auditing.
+
+  - **Machine Learning Data Preparation**
+    Serialize complex data structures used in machine learning pipelines for efficient processing.
+
+  - **Microservice Communication**
+    Serialize complex objects for inter-service communication, ensuring efficient data transfer and reducing the need for complex parsing logic.
+
+  - **Real Estate Portfolio Management**
+    Serialize complex property data for portfolio management and analysis.
+
+  - **Real-time Collaboration Tools**
+    Serialize document or application states for real-time collaboration tools, ensuring consistency across different user sessions.
+
+  - **Research Data Management**
+    Serialize research data and experimental setups for ease of sharing and replication of experiments.
+
+  - **Retail Inventory Management**
+    Serialize inventory data, including details of products, for efficient management and tracking.
+
+  - **Session Continuity Across Devices**
+    Store user session data as a serialized string, enabling users to resume their session on a different device without loss of context.
+
+  - **State Management for Single Page Applications (SPAs)**
+    Serialize UI states into URL-safe strings, enabling bookmarking or sharing of specific application states.
+
+  - **Supply Chain Logistics**
+    Serialize complex logistics and shipment data, aiding in efficient tracking and management.
+
+  - **Telecommunication Network Management**
+    Serialize configurations and states of network devices for efficient management and troubleshooting.
+
+  - **Travel Itinerary Planning**
+    Serialize travel plans and itineraries, allowing users to save and share their travel details easily.
+
+  - **Version Control of Design Files**
+    Serialize design artifacts for version control in graphic design and CAD applications.
+</details>
+
+> :rocket: **Ready to Dive In?**: All the code examples below can be tested on your local machine. Simply clone the repo and run `bin/console` to begin exploring. Don't forget to execute `bundle` first to ensure all dependencies are up to date. Happy coding!
 
 ## Supported Data Types
 
@@ -94,7 +201,6 @@ Universal ID supports most Ruby primitives.
 - `FalseClass`
 - `Float`
 - `Integer`
-- `NilClass`
 - `Range`
 - `Rational`
 - `Regexp`
@@ -217,19 +323,79 @@ Composite support is where things start to get interesting. All of the composite
   ```
 </details>
 
+### Custom Types
+
+Universal ID is **extensible** so you can register your own datatypes with specialized serialization rules.
+It couldn't be simpler. Just convert the required data to a Ruby scalar or composite value.
+
+<details>
+  <summary><b>How to Register your own Datatype</b>... ▾</summary>
+  <p></p>
+
+  ```ruby
+  class UserSettings
+    attr_accessor :user_id, :preferences
+
+    def initialize(user_id, preferences = {})
+      @user_id = user_id
+      @preferences = preferences
+    end
+  end
+
+  UniversalID::MessagePackFactory.register(
+    type: UserSettings,
+    packer: ->(user_preferences, packer) do
+      packer.write user_preferences.user_id
+      packer.write user_preferences.preferences
+    end,
+    unpacker: ->(unpacker) do
+      user_id = unpacker.read
+      preferences = unpacker.read
+      UserSettings.new user_id, preferences
+    end
+  )
+
+  settings = UserSettings.new(1,
+    theme: "dark",
+    notifications: "email",
+    language: "en",
+    layout: "grid",
+    privacy: "private"
+  )
+
+  uri = URI::UID.build(settings).to_s
+  #=> "uid://universal-id/G1QAQAT-bfcGW1QOgadJwJF06yL8gDnGgfs1Xdti20TDDvG5STPqzbYcQ6TBqVKhdZ39CdQZUwEGe..."
+
+  uid = URI::UID.parse(uri)
+  #=> #<URI::UID uid://universal-id/G1QAQAT-bfcGW1QOgadJwJF06yL8gDnGgfs1Xdti20TDDvG5STPqzbYcQ6TBqVKhdZ39CdQZUwEGe..."
+
+  uid.decode
+  => #<UserSettings:0x0000000139157dd8 @preferences={:theme=>"dark", :notifications=>"email", :language=>"en", :layout=>"grid", :privacy=>"private"}, @user_id=1>
+  ```
+</details>
+
 ### Contributed Types
 
 Universal ID is designed to be highly extensible, allowing for third-party contributions to enhance its capabilities.
 These contributions can introduce support for additional data types, further broadening the scope of Universal ID’s utility.
 The following are some notable contrib extensions:
 
-- **ActiveRecord::Base**: Integrates Universal ID with ActiveRecord base models, enabling intelligent serialization of database records
-- **ActiveRecord::Relation**: Supports the serialization of ActiveRecord relations, making it possible to encode complex query structures
-- **ActiveSupport::TimeWithZone**: Adds the ability to serialize ActiveSupport's TimeWithZone objects
-- **GlobalID**: Extends support to include GlobalIDs
-- **SignedGlobalID**: Extends support to include SignedGlobalIDs
+- **ActiveRecord::Base**:
+  Integrates Universal ID with ActiveRecord base models, enabling intelligent serialization of database records.
 
-#### Requiring Contributed Types
+- **ActiveRecord::Relation**:
+  Supports the serialization of ActiveRecord relations, making it possible to encode complex query structures.
+
+- **ActiveSupport::TimeWithZone**:
+  Adds the ability to serialize ActiveSupport's TimeWithZone objects.
+
+- **GlobalID**:
+  Extends support to include GlobalIDs.
+
+- **SignedGlobalID**:
+  Extends support to include SignedGlobalIDs.
+
+**Requiring Contributed Types**
 
 To utilize the contributed types, you must explicitly require them in your application.
 This ensures the extensions are loaded and available for use.
@@ -248,20 +414,29 @@ require "universal_id/contrib/rails"
 
 > :bulb: **Implicit Contribs**: Whenever the `Rails` constant is defined, the related contribs are auto-loaded.
 
-### ActiveRecord
-
-> :information_source: **Broad Compatibility**: Universal ID has built-in support for ActiveRecord, yet it maintains independence from Rails-specific dependencies. This versatile design enables integration into **any Ruby project**.
+> :bulb: **Broad Compatibility**: Universal ID has built-in support for ActiveRecord, yet it maintains independence from Rails-specific dependencies. This versatile design enables integration into **any Ruby project**.
 
-#### Why Universal ID with ActiveRecord?
+**Why Universal ID with ActiveRecord?**
 
 While ActiveRecord already supports GlobalID, a robust library for serializing individual ActiveRecord models, Universal ID extends this functionality to cover a wider range of use cases. Here are a few reasons you may want to consider Universal ID.
 
-- **Support for New Records**: Unlike GlobalID, Universal ID can serialize models that haven't been saved to the database yet
-- **Capturing Unsaved Changes**: It can serialize ActiveRecord models with unsaved changes, ensuring that even transient states are captured
-- **Association Handling**: Universal ID goes beyond single models. It can serialize associated records, including those with unsaved changes, creating a comprehensive snapshot of complex object states
-- **Cloning Existing Records**: Need to make a copy of a record, including its associations? Universal ID handles this effortlessly, making it ideal for duplicating complex datasets
-- **Granular Data Control**: With Universal ID, you gain explicit control over the serialization process. You can precisely choose which columns to include or exclude, allowing for tailored, optimized payloads that fit your specific needs
-- **Efficient Query Serialization**: Universal ID extends its capabilities to ActiveRecord relations, enabling the serialization of complex queries and scopes. This feature allows for seamless sharing of query logic between processes, ensuring consistency and reducing redundancy in data handling tasks.
+- **Support for New Records**:
+  Unlike GlobalID, Universal ID can serialize models that haven't been saved to the database yet.
+
+- **Capturing Unsaved Changes**:
+  It can serialize ActiveRecord models with unsaved changes, ensuring that even transient states are captured.
+
+- **Association Handling**:
+  Universal ID goes beyond single models. It can serialize associated records, including those with unsaved changes, creating a comprehensive snapshot of complex object states.
+
+- **Cloning Existing Records**:
+  Need to make a copy of a record, including its associations? Universal ID handles this effortlessly, making it ideal for duplicating complex datasets.
+
+- **Granular Data Control**:
+  With Universal ID, you gain explicit control over the serialization process. You can precisely choose which columns to include or exclude, allowing for tailored, optimized payloads that fit your specific needs.
+
+- **Efficient Query Serialization**:
+  Universal ID extends its capabilities to ActiveRecord relations, enabling the serialization of complex queries and scopes. This feature allows for seamless sharing of query logic between processes, ensuring consistency and reducing redundancy in data handling tasks.
 
 In summary, while GlobalID excels in its specific use case, Universal ID offers extended capabilities, particularly useful in scenarios involving unsaved records, complex associations, and data cloning.
 
@@ -297,57 +472,6 @@ In summary, while GlobalID excels in its specific use case, Universal ID offers
   ```
 </details>
 
-### Custom Datatypes
-
-Universal ID is **extensible** so you can register your own datatypes with specialized serialization rules.
-It couldn't be simpler. Just convert the required data to a Ruby scalar or composite value.
-
-<details>
-  <summary><b>How to Register your own Datatype</b>... ▾</summary>
-  <p></p>
-
-  ```ruby
-  class UserSettings
-    attr_accessor :user_id, :preferences
-
-    def initialize(user_id, preferences = {})
-      @user_id = user_id
-      @preferences = preferences
-    end
-  end
-
-  UniversalID::MessagePackFactory.register(
-    type: UserSettings,
-    packer: ->(user_preferences, packer) do
-      packer.write user_preferences.user_id
-      packer.write user_preferences.preferences
-    end,
-    unpacker: ->(unpacker) do
-      user_id = unpacker.read
-      preferences = unpacker.read
-      UserSettings.new user_id, preferences
-    end
-  )
-
-  settings = UserSettings.new(1,
-    theme: "dark",
-    notifications: "email",
-    language: "en",
-    layout: "grid",
-    privacy: "private"
-  )
-
-  uri = URI::UID.build(settings).to_s
-  #=> "uid://universal-id/G1QAQAT-bfcGW1QOgadJwJF06yL8gDnGgfs1Xdti20TDDvG5STPqzbYcQ6TBqVKhdZ39CdQZUwEGe..."
-
-  uid = URI::UID.parse(uri)
-  #=> #<URI::UID uid://universal-id/G1QAQAT-bfcGW1QOgadJwJF06yL8gDnGgfs1Xdti20TDDvG5STPqzbYcQ6TBqVKhdZ39CdQZUwEGe..."
-
-  uid.decode
-  => #<UserSettings:0x0000000139157dd8 @preferences={:theme=>"dark", :notifications=>"email", :language=>"en", :layout=>"grid", :privacy=>"private"}, @user_id=1>
-  ```
-</details>
-
 ## Settings and Prepack Options
 
 Universal ID supports a small but powerful set of configuration options for transforming objects before being
@@ -478,7 +602,7 @@ It's also possible to register frequently used options as reusable settings to f
   ```
 
   ```ruby
-  UniversalID::Settings.register :unsaved, YAML.safe_load("app/config/unsaved.yml")
+  UniversalID::Settings.register :unsaved, File.expand_path("app/config/unsaved.yml", __dir__)
   URI::UID.build @record, UniversalID::Settings[:small_record]
   ```
 </details>
@@ -860,6 +984,81 @@ simply convert your UniversalID to a SignedGlobalID to add these features to any
   ```
 </details>
 
+## Fingerprinting (Implicit Versioning)
+
+Fingerprinting adds an extra layer of intelligence to the serialization process.
+UIDs automatically include a "fingerprint" for each serialized object based on the target object's class and
+its modification time _(mtime)_.
+
+Fingerprints are comprised of the following components:
+
+1. `Class (Class)`  - The encoded object's class
+2. `Timestamp (Time)` - The mtime (UTC) of the file that defined the object's class
+
+> :bulb: **Modification Timestamp**: The `mtime` is detected and captured the moment a UID is created.
+
+Fingerprints allow developers to manage different versions of serialized data effectively...**without the need for custom versioning**.
+Whenever the class definition changes, the mtime updates, resulting in a different fingerprint.
+This is especially useful in scenarios where the data format evolves over time, such as in long-lived applications.
+
+<details>
+  <summary><b>How to Use Fingerprinting</b>... ▾</summary>
+  <p></p>
+
+  1. Build a UID using a custom handler _(optional Ruby block)_. This allows you to take control of the encoding process.
+
+  ```ruby
+  # NOTE: The campaign model instance was setup earlier in the "Model Instances" section above
+  campaign.save!
+
+  #           the uid build target (campaign in this case)
+  #                                    |
+  #                                    |  encoding options (whatever was passed to URI::UID.build or {})
+  #                                    |        |
+  uid = URI::UID.build(campaign) do |record, options|
+    # NOTE: this feature is compatible with other tools like kiba, amoeba, etc.
+    #       that can be leveraged to generate the data to be encoded
+
+    data = { id: record.id, demo: true }
+
+    URI::UID.encode data, options.merge(include: %w[id demo]) # block returns the encoded payload
+  end
+  ```
+
+  2. Decode the UID using a custom handler _(optional Ruby block)_. This allows you to take control of the decoding process.
+
+  ```ruby
+  #                                              fingerprint components
+  #                                                     ____|______
+  #                     the decoded payload from above  |         |
+  #                                              |      |         |
+  decoded = URI::UID.parse(uid.to_s).decode do |data, klass, timestamp|
+    # NOTE: this feature is compatible with other tools like kiba, amoeba, etc.
+    #       that can be leveraged to translate the decoded data into the correct format
+
+    record = klass.find_by(id: data[:id])
+    record.instance_variable_set(:@demo, data[:demo])
+
+    case Time.parse(timestamp)
+    when 3.months.ago..Time.now
+      # current data format
+      # return the record as-is
+      record
+    when 1.year.ago..3.months.ago
+      # outdated data format
+      # apply an ETL process to bring the outdated data current
+      # then return the modified record
+      record
+    end
+  end
+  ```
+</details>
+
+Fingerprinting allows for seamless handling of different data versions and formats,
+so you can maintain consistency and reliability in applications dealing with serialized data over time.
+
+> :bulb: **Optional Usage**: While fingerpint creation is automatic and implicit, using it is optional... ready whenever you want more control.
+
 ## Performance and Benchmarks
 
 <details>

data/lib/universal_id/contrib/active_record/base_unpacker.rb

@@ -1,8 +1,6 @@
 # frozen_string_literal: true
 
 class UniversalID::Contrib::ActiveRecordBaseUnpacker
-  using UniversalID::Refinements::KernelRefinement
-
   class << self
     def unpack_with(unpacker)
       class_name = unpacker.read
@@ -13,7 +11,7 @@ class UniversalID::Contrib::ActiveRecordBaseUnpacker
     private
 
     def create_instance(class_name, attributes)
-      klass = const_find(class_name)
+      klass = Object.const_get(class_name) if Object.const_defined?(class_name)
       return nil unless klass
 
       record = if attributes[klass.primary_key]

data/lib/universal_id/contrib/global_id/global_id_model.rb

@@ -15,7 +15,7 @@ class UniversalID::Contrib::GlobalIDModel
     when String
       case universal_id
       when /\A#{URI::UID::SCHEME}/o then URI::UID.parse(universal_id)
-      else URI::UID.parse(URI::UID.build_string(universal_id))
+      else URI::UID.parse(URI::UID.build_string(universal_id, self))
       end
     end
 

data/lib/universal_id/message_pack_types/ruby/composites/module.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+UniversalID::MessagePackFactory.register(
+  type: Module,
+  recreate_pool: false,
+  packer: ->(obj, packer) { packer.write obj.name },
+  unpacker: ->(unpacker) do
+    name = unpacker.read
+    Object.const_defined?(name) ? Object.const_get(name) : nil
+  end
+)

data/lib/universal_id/message_pack_types/ruby/composites/struct.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-using UniversalID::Refinements::KernelRefinement
-
 UniversalID::MessagePackFactory.register(
   type: Struct,
   recreate_pool: false,
@@ -13,11 +11,13 @@ UniversalID::MessagePackFactory.register(
   unpacker: ->(unpacker) do
     class_name = unpacker.read
     hash = unpacker.read
-    klass = const_find(class_name)
+    klass = Object.const_get(class_name) if Object.const_defined?(class_name)
 
-    # shenanigans to support ::Ruby 3.0.X and 3.1.X
-    RUBY_VERSION.start_with?("3.0", "3.1") ?
-      klass.new.tap { |struct| hash.each { |key, val| struct[key] = hash[key] } } :
-      klass.new(**hash)
+    if klass
+      # shenanigans to support ::Ruby 3.0.X and 3.1.X
+      RUBY_VERSION.start_with?("3.0", "3.1") ?
+        klass.new.tap { |struct| hash.each { |key, val| struct[key] = hash[key] } } :
+        klass.new(**hash)
+    end
   end
 )

data/lib/universal_id/message_pack_types.rb

@@ -11,6 +11,7 @@ require_relative "message_pack_types/ruby/scalars/range"
 require_relative "message_pack_types/ruby/scalars/regexp"
 
 # composites
+require_relative "message_pack_types/ruby/composites/module"
 require_relative "message_pack_types/ruby/composites/open_struct"
 require_relative "message_pack_types/ruby/composites/struct"
 require_relative "message_pack_types/ruby/composites/set"

data/lib/universal_id/prepacker.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
-require_relative "refinements"
-
 class UniversalID::Prepacker
-  using UniversalID::Refinements::KernelRefinement
   using UniversalID::Refinements::ArrayRefinement
   using UniversalID::Refinements::HashRefinement
   using UniversalID::Refinements::SetRefinement

data/lib/universal_id/refinements.rb

@@ -2,7 +2,6 @@
 
 module UniversalID::Refinements; end
 
-require_relative "refinements/kernel_refinement"
 require_relative "refinements/array_refinement"
 require_relative "refinements/hash_refinement"
 require_relative "refinements/set_refinement"

data/lib/universal_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module UniversalID
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end

data/lib/universal_id.rb

@@ -5,16 +5,6 @@ require "forwardable"
 require "ostruct"
 require "uri"
 
-require_relative "universal_id/version"
-require_relative "universal_id/settings"
-require_relative "universal_id/encoder"
-require_relative "uri/uid"
-require_relative "universal_id/prepacker"
-require_relative "universal_id/prepack_options"
-require_relative "universal_id/message_pack_factory"
-
-UniversalID::Settings.instance # initialize settings
-
 module UniversalID
   module Contrib; end
 
@@ -26,3 +16,14 @@ module UniversalID
     end
   end
 end
+
+require_relative "universal_id/version"
+require_relative "universal_id/refinements"
+require_relative "universal_id/settings"
+require_relative "universal_id/encoder"
+require_relative "uri/uid"
+require_relative "universal_id/prepacker"
+require_relative "universal_id/prepack_options"
+require_relative "universal_id/message_pack_factory"
+
+UniversalID::Settings.instance # initialize settings

data/lib/uri/uid.rb

@@ -4,24 +4,40 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
 
   module URI
     class UID < ::URI::Generic
-      extend Forwardable
-
+      VERSION = UniversalID::VERSION
       SCHEME = "uid"
       HOST = "universal-id"
 
       class << self
+        def encoder
+          UniversalID::Encoder
+        end
+
+        def fingerprint(object)
+          encode fingerprint_components(object)
+        end
+
         def parse(value)
           components = ::URI.split(value.to_s)
           new(*components)
         end
 
-        def build_string(payload)
-          "#{SCHEME}://#{HOST}/#{payload}"
+        def build_string(payload, object = nil)
+          "#{SCHEME}://#{HOST}/#{payload}##{fingerprint(object)}"
         end
 
-        def build(object, options = {})
-          path = "/#{UniversalID::Encoder.encode(object, options)}"
-          parse "#{SCHEME}://#{HOST}#{path}"
+        def build(object, options = {}, &block)
+          path = "/#{encode(object, options, &block)}"
+          parse "#{SCHEME}://#{HOST}#{path}##{fingerprint(object)}"
+        end
+
+        def encode(object, options = {})
+          return yield(object, options) if block_given?
+          encoder.encode object, options
+        end
+
+        def decode(...)
+          encoder.decode(...)
         end
 
         # Creates a new URI::UID with the given URI components.
@@ -53,15 +69,33 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
             end
           end
         end
+
+        private
+
+        def fingerprint_components(object)
+          klass = object.is_a?(Class) ? object : object.class
+          tokens = [klass]
+
+          begin
+            path = const_source_location(klass.name).first.to_s
+            tokens << ::File.mtime(path).utc if ::File.exist?(path)
+          rescue => e
+            UniversalID.logger&.warn "URI::UID#fingerprint: Unable to determine the source location for #{klass.name}!\n#{e.message}}"
+          end
+
+          tokens
+        end
       end
 
+      alias_method :fingerprint, :fragment
+
       def payload(truncate: false)
         (truncate && path.length > 80) ? "#{path[1..77]}..." : path[1..]
       end
 
       def valid?
         case self
-        in scheme: SCHEME, host: HOST, path: p if p.size >= 8 then return true
+        in scheme: SCHEME, host: HOST, path: p, fragment: _ if p.size >= 8 then return true
         else false
         end
       end
@@ -71,16 +105,29 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
       end
 
       def decode
-        UniversalID::Encoder.decode(payload) if valid?
+        return nil unless valid?
+        return yield(decode_payload, *decode_fingerprint) if block_given?
+
+        decode_payload
       end
 
       def deconstruct_keys(_keys)
-        {scheme: scheme, host: host, path: path}
+        {scheme: scheme, host: host, path: path, fragment: fragment}
       end
 
       def inspect
         "#<URI::UID scheme=#{scheme}, host=#{host}, payload=#{payload truncate: true}>"
       end
+
+      private
+
+      def decode_payload
+        self.class.decode payload
+      end
+
+      def decode_fingerprint
+        self.class.decode fingerprint
+      end
     end
 
     # Register the URI scheme

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: universalid
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-11-14 00:00:00.000000000 Z
+date: 2023-11-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: brotli
@@ -281,6 +281,7 @@ files:
 - lib/universal_id/encoder.rb
 - lib/universal_id/message_pack_factory.rb
 - lib/universal_id/message_pack_types.rb
+- lib/universal_id/message_pack_types/ruby/composites/module.rb
 - lib/universal_id/message_pack_types/ruby/composites/open_struct.rb
 - lib/universal_id/message_pack_types/ruby/composites/set.rb
 - lib/universal_id/message_pack_types/ruby/composites/struct.rb
@@ -297,7 +298,6 @@ files:
 - lib/universal_id/refinements.rb
 - lib/universal_id/refinements/array_refinement.rb
 - lib/universal_id/refinements/hash_refinement.rb
-- lib/universal_id/refinements/kernel_refinement.rb
 - lib/universal_id/refinements/open_struct_refinement.rb
 - lib/universal_id/refinements/set_refinement.rb
 - lib/universal_id/settings.rb
@@ -326,7 +326,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
 summary: URL-Safe String Serialization for any Ruby Object

data/lib/universal_id/refinements/kernel_refinement.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module UniversalID::Refinements::KernelRefinement
-  refine Kernel do
-    # Finds a constant by name, starting at the root namespace (i.e. ::Object)
-    def const_find(name)
-      return nil unless name.is_a?(String)
-      names = name.split("::")
-      constant = Object
-
-      while names.any?
-        value = names.shift
-        constant = constant.const_get(value) if constant.const_defined?(value)
-      end
-
-      (constant.name == name) ? constant : nil
-    end
-  end
-end