Studitemps::Utils

Shared utils for Studitemp's Ruby projects.

Status

Installation

Add this line to your application's Gemfile:

gem'studitemps-utils'

And then execute:

$ bundle

Or install it yourself as:

$ gem install studitemps-utils

URI

An Studitemps Utils URI references similar to a normal URI a specific resource. It contains at least a schema but most of the time when used to reference a resource it also has a context, resource, and an id.

Example: com.example:billing:invoice:R422342

• schema: com.example - Some kind of schema to make URI globally unique.
• context: billing - The context the URI (and the resource) belongs to.
• resource: invoice - The resource type.
• id: R422342 - The resource id.

Usage

require'studitemps/utils/uri'MyBaseURI=Studitemps::Utils::URI.build(schema: 'com.example')InvoiceURI=Studitemps::Utils::URI.build(from: MyBaseURI,context: 'billing',resource: 'invoice')uri=InvoiceURI.new(id: 'R422342')# => #<InvoiceURI 'com.example:billing:invoice:R422342'>uri.to_s# => 'com.example:billing:invoice:R422342'InvoiceURI.build('com.example:billing:invoice:R422342')# => #<InvoiceURI 'com.example:billing:invoice:R422342'>InvoiceURI.build(id: 'R422342')# => #<InvoiceURI 'com.example:billing:invoice:R422342'>InvoiceURI.build(uri)# => #<InvoiceURI 'com.example:billing:invoice:R422342'># `resource` and `id` supports array so that `.build` will verify every value for a given string.# If we also want to check the initializer we can use the "types" extension to do so:require'studitemps/utils/uri/extensions/types'InvoiceURI=Studitemps::Utils::URI.build(schema: 'com.example',context: 'billing',resource: 'invoice',id: %w[finalpast_due])InvoiceURI.build('com.example:billing:invoice:pro_forma')# => Studitemps::Utils::URI::Base::InvalidURIInvoiceURI.new(id: 'final')# => #<InvoiceURI 'com.example:billing:invoice:final'>InvoiceURI.new(id: 'pro_forma')# => Dry::Types::ConstraintError# instead of enums for resources we can also use different URIs with sum types.InvoiceDuplicateURI=Studitemps::Utils::URI.build(from: InvoiceURI,resource: 'invoice_duplicate')InvoicesType=InvoiceURI::Types::URI | InvoiceDuplicateURI::Types::URIInvoicesType[InvoiceURI.new(id: 'final')]# => <#InvoiceURI 'com.example:billing:invoice:final'>InvoicesType[InvoiceDuplicateURI.new(id: 'final')]# => <#InvoiceDuplicateURI 'com.example:billing:invoice:final'>InvoicesType[InvoiceURI.new(id: 'pro_forma')]# => Dry::Types::ConstraintError# regular expressions for `id` are also supportedInvoiceRegexURI=Studitemps::Utils::URI.build(from: InvoiceURI,id: /I-\d{3}/)InvoiceRegexURI.build('com.example:billing:invoice:pro_forma')# => Studitemps::Utils::URI::Base::InvalidURIInvoiceRegexURI.new(id: 'I-123')# => #<InvoiceRegexURI 'com.example:billing:invoice:I-123'>InvoiceRegexURI.new(id: 'pro_forma')# => Dry::Types::ConstraintError# types are also supporteditype=Dry.Types::Coercible::Integer.constrained(gteq: 1000)InvoiceTypeURI=Studitemps::Utils::URI.build(from: InvoiceURI,id: itype)InvoiceTypeURI.build('com.example:billing:invoice:pro_forma')# => Sry::Types::CoercionErrorInvoiceTypeURI.new(id: '1042')# => #<InvoiceTypeURI 'com.example:billing:invoice:1024'>InvoiceTypeURI.new(id: 'pro_forma')# => Dry::Types::ConstraintError# and this can be used in sum types to coerce *distinct* IDs to the correct URIltype=Dry.Types::Coercible::Integer.constrained(lt: 1000)LegacyInvoiceTypeURI=Studitemps::Utils::URI.build(from: InvoiceURI,context: 'legacy_invoice',id: ltype)InvoiceSumType=InvoiceTypeURI::Types::URI | LegacyInvoiceTypeURI::Types::URIInvoiceSumType[id: 23]# => #<LegacyInvoiceTypeURI 'com.example:legacy_invoice:invoice:23'>InvoiceSumType[id: 1023]# => #<InvoiceTypeURI 'com.example:billing:invoice:1023'>InvoiceSumType[id: 'x']# => Dry::Types::CoercionError

Extensions

Extensions add additional functionality to URIs. They can be used by requiring them before building the URI classes.

require'studitemps/utils/uri/extensions/serialization'MyBaseURI=Studitemps::Utils::URI.build(schema: 'com.example')uri=MyBaseURI.new(context: 'billing',resource: 'invoice',id: 'R422342')MyBaseURI.dump(uri)# => 'com.example:billing:invoice:R422342'MyBaseURI.load('com.example:billing:invoice:R422342')# => #<MyBaseURI 'com.example:billing:invoice:R422342'>

Available Extensions

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec 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 push a new release to github:

# gem install gem-release# Patch version
$ gem bump -pts
# Minor version
$ gem bump -v minor -pts

Contributing

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

License

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