universalid 0.1.4 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 21f09da739851c57a622a5c625310dfc99f4770f35f16077a7c5871354ec3312
-  data.tar.gz: 062e4995f803b9e64db5012fb8aa0676c36e903ef3a54731d9e1a6d638943bc8
+  metadata.gz: 626443be00555a2fac0c698df128de29ad2169003bc293e1e1df63ff83cfaf19
+  data.tar.gz: d4f5f42845c42332abbe2b64e5a2fa4139f08e457f9766cce700735003d88e02
 SHA512:
-  metadata.gz: 1de1576929cf3f1c43d74a78aa1b91cf5e5bab778e35677a17819f79ce1c69918c52ef9d003c22248a2d779d6d8bf87cef577fb1c60254e0bf3e7a846d5dc7b2
-  data.tar.gz: 2338b9f4d77f70b122b5993e3659725d3eeb9c695ea884a1a46aff9e45cd3b23a74ade1ad09c6eeb3f3d26185988befb670619566b4a28b19b8146adbb195cc3
+  metadata.gz: e52fef154f9e9dd5660d413707cb2b05619cde795aaf9034ddc311bebe699a40332be0cdc638cc5305bd357473a61f96c15855f88cad8e0e0cbfe33ce56bfb49
+  data.tar.gz: 65f63606908e4a22117285d463b5d96878108320ee92fba133d22ec0fe4f8673cddab66a6a61e95fc3a3bf1e876364d03ee2de3541473da8b3f169899cd865bd

data/README.md

@@ -2,7 +2,7 @@
 
 <p>
   <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-795-47d299.svg" />
+    <img alt="Lines of Code" src="https://img.shields.io/badge/loc-811-47d299.svg" />
   </a>
   <a href="https://codeclimate.com/github/hopsoft/universalid/maintainability">
     <img src="https://api.codeclimate.com/v1/badges/567624cbe733fafc2330/maintainability" />
@@ -33,12 +33,12 @@
   </a>
 </p>
 
-## Fast, recursive, and URL-Safe serialization for any Ruby object.
+## Fast, recursive, optimized, URL-Safe serialization for any Ruby object
 
 Universal ID leverages both [MessagePack](https://msgpack.org/) and [Brotli](https://github.com/google/brotli) _(a combo built for speed and best-in-class data compression)_.
 When combined, these libraries are up to 30% faster and within 2-5% compression rates compared to Protobuf. <a title="Source" href="https://g.co/bard/share/e5bdb17aee91">↗</a>
 
-Universal ID opens the flood gates with a deluge of powerful yet easily implemented [**solutions** ↗](docs/use_cases.md) across a variety of problem domains.
+Universal ID introduces a paradigm shift that enables straightforward simple [**solutions** ↗](docs/use_cases.md) for a variety of complex problem domains.
 
 > [!TIP]
 > All the code examples below can be tested on your local machine. Just clone the repo _(↑or use Gitpod above↑)_ and run `bin/console` to begin exploring.
@@ -48,6 +48,7 @@ Universal ID opens the flood gates with a deluge of powerful yet easily implemen
 
 ## Table of Contents
 
+  - [URI::UID](#uriuid)
   - [Supported Data Types](#supported-data-types)
     - [Primitive Types](#primitive-types)
     - [Composite Types](#composite-types)
@@ -64,6 +65,46 @@ Universal ID opens the flood gates with a deluge of powerful yet easily implemen
 
 <!-- Tocer[finish]: Auto-generated, don't remove. -->
 
+## URI::UID
+
+Universal ID introduces a new URI defintion that can recursively serialize any Ruby object into an URL-safe string
+which can be safely transported via HTTP.
+
+> [!NOTE]
+> The payload is optimized to be as small as possible... _especially notable with large objects._
+
+The best part: **The API is simple.**
+
+```ruby
+data = :ANY_OBJECT_YOU_CAN_IMAGINE
+
+uid = URI::UID.build(data)
+#<URI::UID payload=Cw6AxxoAQU5ZX09CSkVDVF9ZT1VfQ0FOX0lNQ..., fingerprint=CwWAkccHf6ZTeW1ib2wD>
+
+uid.payload
+"Cw6AxxoAQU5ZX09CSkVDVF9ZT1VfQ0FOX0lNQUdJTkUD"
+
+uid.fingerprint
+"CwWAkccHf6ZTeW1ib2wD"
+
+uri = uid.to_s
+"uid://universalid/Cw6AxxoAQU5ZX09CSkVDVF9ZT1VfQ0FOX0lNQUdJTkUD#CwWAkccHf6ZTeW1ib2wD"
+
+parsed = URI::UID.parse(uri)
+#<URI::UID payload=Cw6AxxoAQU5ZX09CSkVDVF9ZT1VfQ0FOX0lNQ..., fingerprint=CwWAkccHf6ZTeW1ib2wD>
+
+parsed.decode
+:ANY_OBJECT_YOU_CAN_IMAGINE
+
+# it's also possible to parse the payload by itself
+
+parsed = URI::UID.from_payload(uid.payload)
+#<URI::UID payload=Cw6AxxoAQU5ZX09CSkVDVF9ZT1VfQ0FOX0lNQ..., fingerprint=CwWAkccHf6ZTeW1ib2wD>
+
+parsed.decode
+:ANY_OBJECT_YOU_CAN_IMAGINE
+```
+
 ## Supported Data Types
 
 ### Primitive Types
@@ -101,7 +142,7 @@ uid.decode
 
 ### Composite Types
 
-Composite _(or compound, complex, etc.)_ datatype support is where things start to get interesting.
+Composite _(or complex, compound, etc.)_ datatype support is where things start to get interesting.
 Universal ID supports the following native Ruby composite datatypes:
 
 - `Array`
@@ -175,7 +216,7 @@ The following extension datatypes ship with Universal ID:
 > [!IMPORTANT]
 > **Why Universal ID with ActiveRecord?**
 > ActiveRecord already has GlobalID, a robust library for serializing individual models.
-> Universal ID covers a much **wider range of use cases**.
+> **Universal ID covers a much wider range of use cases**.
 
 Here are a few reasons you may want to consider Universal ID with ActiveRecord.
 
@@ -195,7 +236,7 @@ Here are a few reasons you may want to consider Universal ID with ActiveRecord.
   Universal ID gives you control over the serialization process. You can choose which columns to include/exclude, allowing for tailored, optimized payloads to fit your needs.
 
 - **Queries/Relations**:
-  Universal ID extends also supports ActiveRecord::Relation, enabling the serialization of complex database queries and scopes.
+  Universal ID also supports ActiveRecord::Relations, enabling the serialization of complex database queries and scopes.
 
 In summary, while GlobalID excels in its specific use case, Universal ID offers more power for use-cases that involve unsaved records, complex associations, data cloning, and database queries.
 
@@ -395,7 +436,7 @@ 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
 
-Fingerprints providate a simple mechanism to help manage versions of the data format... **without the need for explicit versioning**.
+Fingerprints provide a simple mechanism to help manage data format versions... **minimizing the need for custom versioning solutions**.
 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.
 
@@ -466,7 +507,7 @@ copy.save #=> true
 ```
 
 > [!TIP]
-> If you don't need a URL-Safe UID, you can use `UniversalID::Packer` to speed things up.
+> If you don't need a URL-Safe UID, you can use `UniversalID::Packer` to speed things up a bit.
 
 ```ruby
 packed = UniversalID::Packer.pack(campaign, options)

data/lib/universalid/extensions/active_record/base_unpacker.rb

@@ -45,6 +45,7 @@ if defined? ActiveRecord
 
           new_models = models.select(&:new_record?)
           models -= new_models
+          association_collection = record.public_send(name)
 
           # restore persisted models
           # NOTE: ActiveRecord is smart enough to not re-create or re-add
@@ -52,7 +53,10 @@ if defined? ActiveRecord
           record.public_send :"#{name}=", models if models.any?
 
           # restore new unsaved models
-          record.public_send(name).target.concat new_models if new_models.any?
+          association_collection.target.concat new_models if new_models.any?
+
+          # mark association relation as loaded
+          association_collection.proxy_association.instance_variable_set :@loaded, true
         end
       end
     end

data/lib/universalid/extensions/active_support/time_with_zone_message_pack_type.rb

@@ -5,13 +5,13 @@ if defined? ActiveSupport::TimeWithZone
   UniversalID::MessagePackFactory.register(
     type: ActiveSupport::TimeWithZone,
     packer: ->(obj, packer) do
-      packer.write obj.iso8601(9)
-      packer.write obj.zone
+      packer.write obj.to_time.utc
+      packer.write obj.time_zone.tzinfo.identifier
     end,
     unpacker: ->(unpacker) do
-      time = Time.parse(unpacker.read)
-      zone = unpacker.read
-      ActiveSupport::TimeWithZone.new time, ActiveSupport::TimeZone[zone]
+      utc = unpacker.read
+      tz = unpacker.read
+      utc.in_time_zone ActiveSupport::TimeZone[tz]
     end
   )
 

data/lib/universalid/extensions/global_id/global_id_model.rb

@@ -14,14 +14,12 @@ if defined? GlobalID::Identification
     def initialize(universal_id)
       @uid = case universal_id
       when URI::UID then universal_id
-      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, self))
-        end
+      when String then URI::UID.match?(universal_id) ?
+        URI::UID.parse(universal_id) :
+        URI::UID.from_payload(universal_id)
       end
 
-      @id = @uid&.payload
+      @id = uid&.payload
     end
   end
 

data/lib/universalid/extensions/global_id/global_id_uid_extension.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-if defined? GlobalID::Identification && defined? SignedGlobalID
+if defined?(GlobalID::Identification) && defined?(SignedGlobalID)
 
   require "forwardable"
   require_relative "global_id_model"

data/lib/universalid/message_pack_types/{ruby/composites → composites}/struct.rb

@@ -11,7 +11,8 @@ UniversalID::MessagePackFactory.register(
   unpacker: ->(unpacker) do
     class_name = unpacker.read
     hash = unpacker.read
-    klass = Object.const_get(class_name) if Object.const_defined?(class_name)
+    klass = Object.const_get(class_name) if class_name && Object.const_defined?(class_name)
+    klass ||= Struct.new(*hash.keys)
 
     if klass
       # shenanigans to support ::Ruby 3.0.X and 3.1.X

data/lib/universalid/message_pack_types.rb

@@ -3,21 +3,21 @@
 # NOTE: MessagePack scans registered type in linear order and first match wins
 
 # scalars
-require_relative "message_pack_types/ruby/scalars/bigdecimal"
-require_relative "message_pack_types/ruby/scalars/complex"
-require_relative "message_pack_types/ruby/scalars/rational"
-require_relative "message_pack_types/ruby/scalars/date_time"
-require_relative "message_pack_types/ruby/scalars/date"
-require_relative "message_pack_types/ruby/scalars/range"
-require_relative "message_pack_types/ruby/scalars/regexp"
+require_relative "message_pack_types/scalars/bigdecimal"
+require_relative "message_pack_types/scalars/complex"
+require_relative "message_pack_types/scalars/rational"
+require_relative "message_pack_types/scalars/date_time"
+require_relative "message_pack_types/scalars/date"
+require_relative "message_pack_types/scalars/range"
+require_relative "message_pack_types/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"
+require_relative "message_pack_types/composites/module"
+require_relative "message_pack_types/composites/open_struct"
+require_relative "message_pack_types/composites/struct"
+require_relative "message_pack_types/composites/set"
 
 # extensions
-Dir["#{__dir__}/extensions/**/*.rb"].each { |f| require f }
+Dir["#{__dir__}/extensions/**/*.rb"].sort.each { |f| require f }
 
 UniversalID::MessagePackFactory.create_msgpack_pool

data/lib/universalid/settings.rb

@@ -39,7 +39,7 @@ class UniversalID::Settings
       in include_keys: include_keys then to.prepack.database.include_keys = !!include_keys
       in include_timestamps: include_timestamps then to.prepack.database.include_timestamps = !!include_timestamps
       in include_changes: include_changes then to.prepack.database.include_changes = !!include_changes
-      in include_unsaved_changes: include_changes then to.prepack.database.include_changes = !!include_unsaved_changes # TODO: Remove in v1.0
+      in include_unsaved_changes: include_changes then to.prepack.database.include_changes = !!include_changes # TODO: Remove in v1.0
       in include_descendants: include_descendants then to.prepack.database.include_descendants = !!include_descendants
       in descendant_depth: descendant_depth then to.prepack.database.descendant_depth = descendant_depth
       else # ignore key

data/lib/universalid/version.rb

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

data/lib/uri/uid.rb

@@ -9,6 +9,7 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
       VERSION = UniversalID::VERSION
       SCHEME = "uid"
       HOST = "universalid"
+      PATTERN = /\A#{SCHEME}:\/\/#{HOST}\/[-_0-9A-Z]+#[-_0-9A-Z]+\z/io
 
       class << self
         def encoder
@@ -29,6 +30,11 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
           new(*::URI.split(value))
         end
 
+        def match?(uri)
+          return true if uri.is_a?(self)
+          uri.to_s.match? PATTERN
+        end
+
         def build_string(payload, object = nil)
           "#{SCHEME}://#{HOST}/#{payload}##{fingerprint(object)}"
         end
@@ -38,6 +44,17 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
           parse "#{SCHEME}://#{HOST}#{path}##{fingerprint(object)}"
         end
 
+        def from_payload(payload, object = nil)
+          parse(build_string(payload, object)).tap do |uid|
+            # NOTE: fingerprint mismatch can happen when building from a UID payload
+            #       ensure the fingerprint is correct
+            if uid&.valid? && URI::UID.fingerprint(uid.decode) != uid.fingerprint
+              remove_instance_variable :@decoded_fingerprint if instance_variable_defined?(:@decoded_fingerprint)
+              uid.instance_variable_set :@fragment, URI::UID.build(uid.decode).fingerprint
+            end
+          end
+        end
+
         def encode(object, options = {})
           return yield(object, options) if block_given?
           encoder.encode object, options
@@ -99,7 +116,7 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
       end
 
       def fingerprint(decode: false)
-        return decode_fingerprint if decode
+        return @decoded_fingerprint ||= decode_fingerprint if decode
         fragment
       end
 
@@ -114,11 +131,14 @@ unless defined?(::URI::UID) || ::URI.scheme_list.include?("UID")
         !valid?
       end
 
-      def decode
+      def decode(force: false)
         return nil unless valid?
-        return yield(decode_payload, *decode_fingerprint) if block_given?
 
-        decode_payload
+        remove_instance_variable :@decoded if force && instance_variable_defined?(:@decoded)
+        return @decoded if defined?(@decoded)
+
+        @decoded ||= yield(decode_payload, *decode_fingerprint) if block_given?
+        @decoded ||= decode_payload
       end
 
       def deconstruct_keys(_keys)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: universalid
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.6
 platform: ruby
 authors:
 - Nate Hopkins (hopsoft)
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-01-11 00:00:00.000000000 Z
+date: 2024-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -332,6 +332,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '1.32'
+- !ruby/object:Gem::Dependency
+  name: timecop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: |
   Universal ID opens the flood gates with a deluge of profoundly powerful
   yet easily implemented new use-cases for your apps and scripts.
@@ -358,17 +372,17 @@ files:
 - lib/universalid/extensions/signed_global_id/message_pack_type.rb
 - lib/universalid/message_pack_factory.rb
 - lib/universalid/message_pack_types.rb
-- lib/universalid/message_pack_types/ruby/composites/module.rb
-- lib/universalid/message_pack_types/ruby/composites/open_struct.rb
-- lib/universalid/message_pack_types/ruby/composites/set.rb
-- lib/universalid/message_pack_types/ruby/composites/struct.rb
-- lib/universalid/message_pack_types/ruby/scalars/bigdecimal.rb
-- lib/universalid/message_pack_types/ruby/scalars/complex.rb
-- lib/universalid/message_pack_types/ruby/scalars/date.rb
-- lib/universalid/message_pack_types/ruby/scalars/date_time.rb
-- lib/universalid/message_pack_types/ruby/scalars/range.rb
-- lib/universalid/message_pack_types/ruby/scalars/rational.rb
-- lib/universalid/message_pack_types/ruby/scalars/regexp.rb
+- lib/universalid/message_pack_types/composites/module.rb
+- lib/universalid/message_pack_types/composites/open_struct.rb
+- lib/universalid/message_pack_types/composites/set.rb
+- lib/universalid/message_pack_types/composites/struct.rb
+- lib/universalid/message_pack_types/scalars/bigdecimal.rb
+- lib/universalid/message_pack_types/scalars/complex.rb
+- lib/universalid/message_pack_types/scalars/date.rb
+- lib/universalid/message_pack_types/scalars/date_time.rb
+- lib/universalid/message_pack_types/scalars/range.rb
+- lib/universalid/message_pack_types/scalars/rational.rb
+- lib/universalid/message_pack_types/scalars/regexp.rb
 - lib/universalid/message_pack_types/uri/uid/type.rb
 - lib/universalid/packer.rb
 - lib/universalid/prepack_database_options.rb
@@ -404,8 +418,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.32
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
-summary: Fast, recursive, and URL-Safe serialization for any Ruby object.
+summary: Fast, recursive, optimized, URL-Safe serialization for any Ruby object
 test_files: []