standard_procedure_global_id_serialiser 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9eff9d8c190f3ca46f9cb3fefe13872986a83cce360f8997e3d915cb37950cf5
-  data.tar.gz: '0943652b089c5c1a4258f4f58eda5ff1c3aaf13cee3fd1d9e0d6337f3f72a14a'
+  metadata.gz: 8a2dbf92f0c7144ab7190ad6e6f284acdfdf2ff5595888e725f7d6fcd8d5a057
+  data.tar.gz: 350946224c236cf89f1c09d21cba74b6a8333ec2e4f13767936ca2b68652c005
 SHA512:
-  metadata.gz: aa440b80823fa8029a5052763b36e3d8b13ba5f73c428d5e480f6d95534d8fc2d6d4dd9e53709380baab989463556d0c02c1473c3abf0cf4325576de62e9cee9
-  data.tar.gz: 7ea366f74494b5afcd80c29a8ebd3633090d0fbc70414b2a4e571063b9286b936e9f657ba82bc53087fa3b3db41a16aa2ef452754ea6cf27250d2ac52d46ea9a
+  metadata.gz: 72db94a95ae5c5667e979a8a60ad5f00a265603fa2cb3e966b36263f99e50953fb6031f01708d8050848b848b8d057c66f2fa3a7f5f41cabe8cdfc2375b46ee7
+  data.tar.gz: 74b22b14271c999222ad6c9ebee4979da9e077944aaddcdaf0331beeec36fb4a4b33d860eff64b8374eb28b1e8f1c58b973cad2936c430e492ad9e52b91955c0

data/README.md

@@ -4,7 +4,26 @@ A [Ruby on Rails serialiser](https://api.rubyonrails.org/classes/ActiveRecord/At
 
 ## Usage
 
-Create your ActiveRecord model, declaring your serialised field as normal.  But instead of declaring the `coder` as `JSON`, use `GlobalIdSerialiser`.
+### Outside of Rails serialisation
+
+Rails serialisation uses the `GlobalIdSerialiser#dump` and `GlobalIdSerialiser#load` methods - which convert your data to and from JSON.  
+
+However, internally, these methods use `GlobalIdSerialiser#marshal` and `GlobalIdSerialiser#unmarshal`.  These do the conversion from GlobalID to model and back again, without the conversion to JSON.  So you can use these anywhere that expects standard ruby objects.  
+
+```ruby
+@alice = Person.create name: "Alice"
+@data = { title: "Welcome to my blog", author: @alice }
+
+@marshalled_data = GlobalIdSerialiser.marshal @data 
+puts @marshalled_data # => { title: "Welcome to my blog", author: "gid://my_app/person/1" }
+
+@unmarshalled_data = GlobalIdSerialiser.unmarshal @marshalled_data 
+puts @unmarshalled_data # => { title: "Welcome to my blog", author: Person<id: 1, name: "Alice"> }
+```
+
+### Serialising data to and from ActiveRecord
+
+Create your ActiveRecord model, declaring your serialised field - but instead of declaring the `coder` as `JSON`, use `GlobalIdSerialiser`.
 
 ```ruby
 class BlogPost < ApplicationRecord 
@@ -19,13 +38,21 @@ Then go about your day, safely storing your models in your serialised field.
 
 @blog_post = BlogPost.create data: { title: "Welcome to my blog", author: @alice }
 
-puts @blog_post.data # => { "title": "Welcome to my blog", "author": "gid://my_app/person/1" }
+puts @blog_post.data_before_type_cast # => '{"title":"Welcome to my blog","author":"gid://my_app/person/1"}'
 
 @reloaded_blog_post = BlogPost.find @blog_post.id 
 
 puts @blog_post.data["author"] # => Person<id: 1, name: "Alice">
 ```
 
+### Deleted records
+
+When your data is marshalled, any objects that implement `GlobalID::Identification` get converted to a GlobalID URI string.  
+
+Later, when that data is unmarshalled, any GlobalID URIs are passed to the `GlobalID::Locator` to find them in the database.  If the record in question has been deleted, the data will be unmarshalled as `nil`.  This is so as much of the data as possible is retrieved without raising any `ActiveRecord::RecordNotFound` errors (which would stop the unmarshalling process part-way through and leave you with no data at all).  
+
+So be aware that `nil`s may be returned if the record in question has been deleted.  
+
 ## Installation
 
 Add it to your Gemfile.  `bundle install`.  Relax.  

data/checksums/standard_procedure_global_id_serialiser-0.1.2.gem.sha512

@@ -0,0 +1 @@
+e55756bb70b00d06279f3c2ce6ed27da16b88f1c7d606fb835eb2159f90120643026872dd56701ce5813dff39596d65a3f9d7bf103d522412ea4ef6ff68ff26f

data/lib/global_id_serialiser/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class GlobalIdSerialiser
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/global_id_serialiser.rb

@@ -6,9 +6,13 @@ require "global_id"
 require "json"
 
 class GlobalIdSerialiser
-  def self.dump(data) = JSON.generate(pack(data))
+  def self.marshal(data) = pack(data)
 
-  def self.load(json) = unpack(JSON.parse(json))
+  def self.dump(data) = JSON.generate(marshal(data))
+
+  def self.unmarshal(data) = unpack(data)
+
+  def self.load(json) = unmarshal(JSON.parse(json))
 
   private_class_method def self.pack argument
     case argument

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: standard_procedure_global_id_serialiser
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Rahoul Baruah
 bindir: exe
 cert_chain: []
-date: 2025-03-11 00:00:00.000000000 Z
+date: 2025-03-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: globalid
@@ -52,6 +52,7 @@ files:
 - Rakefile
 - checksums/standard_procedure_global_id_serialiser-0.1.0.gem.sha512
 - checksums/standard_procedure_global_id_serialiser-0.1.1.gem.sha512
+- checksums/standard_procedure_global_id_serialiser-0.1.2.gem.sha512
 - lib/global_id_serialiser.rb
 - lib/global_id_serialiser/version.rb
 - lib/standard_procedure_global_id_serialiser.rb