This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Dude

Dude is a dead simple Redis cache that supports multiple storage backends.

Installation

1. Add the dependency to your shard.yml:

   dependencies:
     dude:
       github: GrottoPress/dude
     #redis: # Uncomment if using the Redis backend
     #  github: jgaskins/redis
     #pg: # Uncomment if using the Posgres backend
     #  github: will/crystal-pg

2. Run shards update

3. Require and configure Dude:

   • Using the Redis backend

     # ->>> src/app/config.cr
     
     # ...
     
     require "dude/redis"
     
     Dude.configure do |settings|
       settings.store = Dude::Redis.new(ENV["REDIS_URL"], namespace: "dude")
     end
     
     # ...

   • Using the Postgres backend

     # ->>> src/app/config.cr
     
     # ...
     
     require "dude/postgres"
     
     Dude.configure do |settings|
       # ...
       settings.store = Dude::Postgres.new(ENV["DATABASE_URL"], namespace: "dude")
       # OR pass an existing `DB::Database` instance
       #settings.store = Dude::Postgres.new(db, namespace: "dude")
       # ...
     end
     
     # You may use this in your app's migrations to migrate
     Dude.postgres.migrate_database
     
     # You may use this in your app's migrations to roll back
     #Dude.postgres.rollback_database
     
     # ...

   • Using the Memory backend

     # ->>> src/app/config.cr
     
     # ...
     
     require "dude"
     
     Dude.configure do |settings|
       settings.store = Dude::Memory.new
     end
     
     # ...

   • Skip caching

     You may disable cache altogether by setting Dude.settings.store to nil (This is the default).

Usage

• Fetch raw value from cache

  # Sets and returns block if key not found in cache
  Dude.get("key", 1.minute) { "value" } # => `value`

• Fetch JSON-serializable value from cache

  struct User
    include JSON::Serializable
  
    getter id : Int32
  
    def initialize(@id)
    end
  end
  
  # Sets and returns block if key not found in cache
  Dude.get(User, "key", 1.minute) { User.new(2) } # => `User(@id=2)`

• Perform multiple operations using a transaction

  Dude.transaction do |store|
    Dude.set("key_1", "value1", 1.minute, store)
    Dude.set("key_2", "value2", 3.minutes, store)
    Dude.delete("key_3", store)
  end

Development

Create a .env.sh file:

#!/usr/bin/env bash

export COCKROACH_URL='postgres://root@localhost:26257/dude_spec?sslmode=disable'
export POSTGRES_URL='postgres://postgres:password@localhost:5432/dude_spec'
export REDIS_URL='redis://localhost:6379/0'

Update the file with your own details. Then run tests with source .env.sh && crystal spec.

Contributing

1. Fork it
2. Switch to the master branch: git checkout master
3. Create your feature branch: git checkout -b my-new-feature
4. Make your changes, updating changelog and documentation as appropriate.
5. Commit your changes: git commit
6. Push to the branch: git push origin my-new-feature
7. Submit a new Pull Request against the GrottoPress:master branch.