Paquito provies utility classes to define optimized and evolutive serializers.

Add this line to your application's Gemfile:

gem 'paquito'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install paquito

Paquito::CoderChain combines two or more serializers into one.

Example:

compressed_yaml_coder = Paquito.chain(YAML, Zlib)
payload = compressed_yaml_coder.dump({ foo: 42 }) # YAML compressed with gzip
compressed_yaml_coder.load(payload) # => { foo: 42 }

Paquito::ConditionalCompressor compresses payloads if they are over a defined size.

Example:

coder = Paquito::ConditionalCompressor.new(Zlib, 256)
coder.dump("foo") # => "\x00foo"
coder.dump("foo" * 500) # => "\x01<compressed-data....>"

Paquito::SingleBytePrefixVersion prepends a version prefix to the payloads, which allows you to seamlessly transition between different serialization methods.

The first argument is the current version used for newly generated payloads.

Example:

coder = Paquito::SingleBytePrefixVersion.new(1,
  0 => YAML,
  1 => JSON,
  2 => MessagePack,
)
coder.dump([1]) # => "\x01[1]"
coder.load("\x00---\n:foo: 42") # => { foo: 42 }

Similar to the single byte prefix, but meant to be human readable and to allow for migrating unversioned payloads.

Payloads without a version prefix are assumed to be version 0.

The first argument is the current version used for newly generated payloads.

Example:

coder = Paquito::CommentPrefixVersion.new(1,
  0 => YAML,
  1 => JSON,
)

coder.load("---\n:foo: 42") # => { foo: 42 }
coder.dump([1]) # => "#☠1☢\n[1]"

In some situations where you'd rather not serialize nil, you can use the Paquito.allow_nil shorthand:

coder = Paquito.allow_nil(Marshal)
coder.dump(nil) # => nil
coder.load(nil) # => nil

If you do need to handle serialization or deserialization errors, for instance to fallback to acting like a cache miss, Paquito::TranslateErrors translates all underlying exceptions into Paquito::Error descendants.

Example:

coder = Paquito::TranslateErrors.new(Paquito::CoderChain.new(YAML, Zlib))
coder.load("\x00") # => Paquito::UnpackError (buffer error)

Paquito::CodecFactory is a utility facade to create advanced MessagePack factories with support for common Ruby and Rails types.

Example

coder = Paquito::CodecFactory.build([Symbol, Set])
coder.load(coder.dump(%i(foo bar).to_set)) # => #<Set: {:foo, :bar}>

Paquito::TypedStruct is a opt-in Sorbet runtime plugin that allows T::Struct classes to be serializable. You need to explicitly include the module in the T::Struct classes that you will be serializing.

Example

class MyStruct < T::Struct
  include Paquito::TypedStruct

  prop :foo, String
  prop :bar, Integer
end

my_struct = MyStruct.new(foo: "foo", bar: 1)

my_struct.as_pack # => [26450, "foo", 1]
MyStruct.from_pack([26450, "foo", 1]) # => <MyStruct bar=1, foo="foo">

paquito doesn't depend on rails or any of its components, however it does provide some optional utilities.

Paquito::CacheEntryCoder turns an ActiveSupport::Cache::Entry instance into a simple Array instance. This allows you to implement custom coders for ActiveSupport::Cache.

Example:

ActiveSupport::Cache::FileStore.new("tmp/cache", coder: Paquito.chain(Paquito::CacheEntryCoder, JSON))

Paquito::SerializedColumn allows you to decorate any encoder to behave like Rails's builtin YAMLColumn

Example:

class Shop < ActiveRecord::Base
  serialize :settings, Paquito::SerializedColumn.new(
    Paquito::CommentPrefixVersion.new(
      1,
      0 => YAML,
      1 => Paquito::CodecFactory.build([Symbol]),
    ),
    Hash,
    attribute_name: :settings,
  )
end

Shop.new.settings # => {}

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.

Bug reports and pull requests are welcome on GitHub at https://github.com/Shopify/paquito.

The gem is available as open source under the terms of the MIT License.