{"id":15605697,"url":"https://github.com/gangelo/immutable_struct_ex_redactable","last_synced_at":"2025-05-07T13:45:26.443Z","repository":{"id":60664627,"uuid":"544183664","full_name":"gangelo/immutable_struct_ex_redactable","owner":"gangelo","description":"immutable_struct_ex_redactable is the redactable version of the world-famous immutable_struct_ex immutable struct :). To find out more about the immutable_struct_ex gem, visit the Rubygems.org entry for immutable_struct_ex.  immutable_struct_ex_redactable maintains all the functionality of the immutable_struct_ex gem, but allows you to create immutable structs that can be configured to redact field values using standard gem configuration (ImmutableStructExRedactable.configure { |config| ... }) or by passing configuration options to the appropriate method (ImmutableStructExRedactable.create_with(config, ...))","archived":false,"fork":false,"pushed_at":"2024-08-10T00:53:01.000Z","size":55,"stargazers_count":2,"open_issues_count":3,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T10:42:25.767Z","etag":null,"topics":["immutable","immutable-state","immutable-store","immutable-struct","ruby","ruby-gem","ruby-struct","ruby-structs","rubygem","rubygems"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gangelo.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-10-01T21:34:10.000Z","updated_at":"2024-08-10T00:53:06.000Z","dependencies_parsed_at":"2024-01-20T02:34:52.467Z","dependency_job_id":"fe1b5410-cf19-4c5d-ad76-c87da82c9e4f","html_url":"https://github.com/gangelo/immutable_struct_ex_redactable","commit_stats":{"total_commits":17,"total_committers":1,"mean_commits":17.0,"dds":0.0,"last_synced_commit":"0bc0689d9dfd093db14c41de7afdbda11496a7f3"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gangelo%2Fimmutable_struct_ex_redactable","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gangelo%2Fimmutable_struct_ex_redactable/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gangelo%2Fimmutable_struct_ex_redactable/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gangelo%2Fimmutable_struct_ex_redactable/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gangelo","download_url":"https://codeload.github.com/gangelo/immutable_struct_ex_redactable/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252889687,"owners_count":21820226,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["immutable","immutable-state","immutable-store","immutable-struct","ruby","ruby-gem","ruby-struct","ruby-structs","rubygem","rubygems"],"created_at":"2024-10-03T04:11:36.453Z","updated_at":"2025-05-07T13:45:26.417Z","avatar_url":"https://github.com/gangelo.png","language":"Ruby","readme":"# `immutable_struct_ex_redactable`\n\n[![Ruby](https://github.com/gangelo/immutable_struct_ex_redactable/actions/workflows/ruby.yml/badge.svg)](https://github.com/gangelo/immutable_struct_ex_redactable/actions/workflows/ruby.yml)\n[![GitHub version](http://badge.fury.io/gh/gangelo%2Fimmutable_struct_ex_redactable.svg?version=8)](https://badge.fury.io/gh/gangelo%2Fimmutable_struct_ex_redactable)\n[![Gem Version](https://badge.fury.io/rb/immutable_struct_ex_redactable.svg?version=8)](https://badge.fury.io/rb/immutable_struct_ex_redactable)\n[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://www.rubydoc.info/gems/immutable_struct_ex_redactable/) [![Report Issues](https://img.shields.io/badge/report-issues-red.svg)](https://github.com/gangelo/immutable_struct_ex_redactable/issues)\n[![License](http://img.shields.io/badge/license-MIT-yellowgreen.svg)](#license)\n\n## Introduction\n\n`immutable_struct_ex_redactable` is the _redactable version_ of the world-famous _immutable_struct_ex_ immutable struct :). To find out more about the _immutable_struct_ex_ gem, visit the Rubygems.org entry for [immutable_struct_ex](https://rubygems.org/gems/immutable_struct_ex).\n\n`immutable_struct_ex_redactable` maintains all the functionality of the _immutable_struct_ex_ gem, but allows you to create immutable structs that can be configured to redact field values using standard gem configuration (`ImmutableStructExRedactable.configure { |config| ... }`) or by passing configuration options to the appropriate method (`ImmutableStructExRedactable.create_with(config, ...)`).\n\nNOTE: both **whitelisting** and **blacklisting** are supported.\n\n## Usage\n\nFollow the instructions for [Installation](#installation) first, to incorporate this gem into your code.\n\n### Basic usage\n\n#### Configure Gem Global Defaults\n\n_immutable_struct_ex_redactable_, by default, will redact fields named `:password` using the redacted label `\"******\"`. This will not meet your needs in all circumstances most likely. If this is _not_ the case, you may change the fields that are redacted and the redactable label by changing the _immutable_struct_ex_redactable_ configuration via the `#whitelist` or `#blacklist` configuration options:\n\n##### Using a whitelist\n\n```ruby\nImmutableStructExRedactable::configure do |config|\n  config.whitelist = %i[first last]\n  config.redacted_label = '[REDACTED]'\nend\n\nfields = {\n  first: 'John',\n  last: 'Smith',\n  password: 'p@ssw0rd',\n  dob: '1986-05-12'\n}\n\nImmutableStructExRedactable.create(**fields)\n=\u003e #\u003cstruct  first=\"John\", last=\"Smith\", password=\"[REDACTED]\", dob=\"[REDACTED]\"\u003e\n\nfields = {\n  first: 'Jane',\n  last: 'Smith',\n  password: 'h3l10W04lD',\n  dob: '1990-12-26'\n}\n\nImmutableStructExRedactable.create(**fields)\n=\u003e #\u003cstruct  first=\"Jane\", last=\"Smith\", password=\"[REDACTED]\", dob=\"[REDACTED]\"\u003e\n```\n\n##### Using a blacklist\n\n```ruby\nImmutableStructExRedactable::configure do |config|\n  config.blacklist = %i[password dob ssn phone]\n  config.redacted_label = '[REDACTED]'\nend\n\nfields = {\n  first: 'John',\n  last: 'Smith',\n  password: 'p@ssw0rd',\n  dob: '1986-05-12'\n}\n\nImmutableStructExRedactable.create(**fields)\n=\u003e #\u003cstruct  first=\"John\", last=\"Smith\", password=\"[REDACTED]\", dob=\"[REDACTED]\"\u003e\n\nfields = {\n  first: 'Jane',\n  last: 'Smith',\n  password: 'h3l10W04lD',\n  dob: '1990-12-26'\n}\n\nImmutableStructExRedactable.create(**fields)\n=\u003e #\u003cstruct  first=\"Jane\", last=\"Smith\", password=\"[REDACTED]\", dob=\"[REDACTED]\"\u003e\n```\n\nNOTE: Setting the global defaults in the above manner will affect **every** _immutable_struct_ex_redactable_ struct instance you create unless you override the global configuration options, by passing a custom configuration.\n\n#### Overriding the Global Configuration Options\n\nTo override the global configuration options, you may do so by calling the `ImmutableStructExRedactable#create_with` method in the following manner:\n\n```ruby\n# Create a custom configuration with the options you want to use.\ncustom_config = ImmutableStructExRedactable::Configuration.new.tap do |config|\n  config.whitelist = %i[first last]\n  config.redacted_label = '[NO WAY JOSE]'\nend\n\nfields = {\n  first: 'John',\n  last: 'Smith',\n  password: 'p@ssw0rd',\n  dob: '1986-05-12'\n}\n\n# Call the #create_with method passing the custom configuration options.\nImmutableStructExRedactable.create_with(custom_config, **fields)\n=\u003e #\u003cstruct  first=\"John\", last=\"Smith\", password=\"[NO WAY JOSE]\", dob=\"[NO WAY JOSE]\"\u003e\n```\n\n### Access to the Original Redacted Field Values\n\nBy default, _immutable_struct_ex_redactable_ **will not** allow access to redacted field values; that is, field values marked for redaction via the global configuration (`ImmutableStructExRedactable::Configuration#whitelist/#blacklist`) or by overriding the global configuration by passing a custom configuration (`ImmutableStructExRedactable.create_with(my_config, ...)`). However, if you really _need_ access to redacted field values in their original, *un*redacted form, you can turn on the `ImmutableStructExRedactable::Configuration#redacted_unsafe` option in the global configuration or turn this same option on when passing a custom configuration. Turning the `redacted_unsafe` configuration option on in either scenario will instruct _immutable_struct_ex_redactable_ to create _private methods_ on structs created that will allow access to the original *un*redacted field values via `send:`. The _private methods_ created that will allow access to the original *un*redacted field values, will have the following naming convention:\n\n```ruby\nunredacted_\u003credacted field\u003e\n# Where \u003credacted field\u003e == the Symbol of the redacted field.\n# For example: unredacted_password, unredacted_dob, unredacted_ssn, etc.\n```\n\nFor example:\n\n```ruby\ncustom_config = ImmutableStructExRedactable::Configuration.new.tap do |config|\n  config.whitelist = %i[username]\n  config.redacted_unsafe = true\nend\n\nhash = { username: 'jsmith', password: 'p@ssw0rd' }\nstruct = ImmutableStructExRedactable.create_with(custom_config, **hash) do\n  def to_h_unredacted\n    {\n      username: username,\n      password: send(:unredacted_password)\n    }\n  end\nend\n=\u003e #\u003cstruct  username=\"jsmith\", password=\"******\"\u003e\n\nstruct.unredacted_password\n#=\u003e NoMethodError: private method `unredacted_password' called for #\u003cstruct username=\"jsmith\", password=\"******\"\u003e...\n\nstruct.send :unredacted_password\n#=\u003e \"p@ssw0rd\"\n\nstruct.to_h_unredacted\n#=\u003e {:username=\u003e\"jsmith\", :password=\u003e\"p@ssw0rd\"}\n```\n\n### \u0026blocks are Permitted\n\nCurrent `immutable_struct_ex` gem functionality is still available, so passing `\u0026block` is permitted. See [immutable_struct_ex](https://rubygems.org/gems/immutable_struct_ex) gem for more details:\n\n```ruby\nfields = { first: 'John', last: 'Smith', password: 'p@ssw0rd' }\n\nstruct = ImmutableStructExRedactable.create(**fields) do\n  def full_name\n    \"#{first} #{last}\"\n  end\nend\n\nstruct.full_name\n=\u003e \"John Smith\"\n```\n\n### Miscellaneous Examples\n\n```ruby\nclass MyRedactableImmutableStruct\n  include ImmutableStructExRedactable\n\n  class \u003c\u003c self\n    def create\n      self.new.send(:execute)\n    end\n  end\n\n  private\n\n  attr_reader :results\n\n  def execute\n    @results ||= create_with(config, username: 'jsmith', password: 'p@ssw0rd') do\n      def jsmith?\n        username == 'jsmith'\n      end\n    end\n  end\n\n  def config\n    @config ||= ImmutableStructExRedactable::Configuration.new.tap do |config|\n      config.whitelist = %i[username]\n      config.redacted_label = 'xxxxxx'\n    end\n  end\nend\n\nresults = MyRedactableImmutableStruct.create\n#=\u003e #\u003cstruct  username=\"jsmith\", password=\"xxxxxx\"\u003e\n\nresults.jsmith?\n#=\u003e true\n```\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'immutable_struct_ex_redactable'\n```\n\nAnd then execute:\n\n    $ bundle install\n\nOr install it yourself as:\n\n    $ gem install immutable_struct_ex_redactable\n\n## Development\n\nAfter 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.\n\nTo 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](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/immutable_struct_ex_redactable. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/immutable_struct_ex_redactable/blob/main/CODE_OF_CONDUCT.md).\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the ImmutableStructExRedactable project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/immutable_struct_ex_redactable/blob/main/CODE_OF_CONDUCT.md).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgangelo%2Fimmutable_struct_ex_redactable","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgangelo%2Fimmutable_struct_ex_redactable","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgangelo%2Fimmutable_struct_ex_redactable/lists"}