Paquito

Paquito provies utility classes to define optimized and evolutive serializers.

Installation

Add this line to your application's Gemfile:

gem 'paquito'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install paquito

Usage

chain

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 }

ConditionalCompressor

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....>"

SingleBytePrefixVersion

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 }

CommentPrefixVersion

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]"

allow_nil

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

TranslateErrors

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)

CodecFactory

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}>

TypedStruct

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">

Rails utilities

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

CacheEntryCoder

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))

SerializedColumn

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 # => {}

Development

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.

Contributing

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

License

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