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

Punching Bag

A Crystal shard for tracking and analyzing hit counts, trending items, and time-based analytics.

Features

• Total hit count tracking
• Most hit items tracking
• Time-based hit analytics
• Lightweight and fast

Requirements

• Crystal >= 1.0.0

Installation

1. Add Punching Bag to your shard.yml:

dependencies:
  punching_bag:
    github: dcalixto/punching_bag

2. Install dependencies:

shards install

3. Run the setup command:

crystal run bin/punching_bag.cr -- setup

If the setup has already been completed, you will see the following message in your terminal:

Setup already completed.

Usage

Import the library

require "punching_bag"

Then in your application code, you can set it up like:

Initialize database connection

database = DB.open(DATABASE_URL)
PunchingBag.db = database

Initialize the Bag

bag = PunchingBag.new

Record a hit

bag.punch("Article", 1)

Record multiple hits

bag.punch("Article", 1, hits: 5)

Record hit with timestamp

bag.punch("Article", 1, timestamp: Time.utc - 1.day)

Analytics

Get total hits for an item

total = bag.total_hits("Article", 1)

Get most hit items since last week

trending = bag.most_hit(Time.utc - 1.week)

Get top 10 most hit items since last month

top_items = bag.most_hit(Time.utc - 1.month, limit: 10)

Get average time for hits

avg_time = bag.average_time("Article", 1)

Clear all recorded hits

bag.clear

Example Integration

Here’s an example of integrating Punching Bag into an application.

require "punching_bag"
require "db/serializable"

class Article
 include DB::Serializable

   property id : Int64
   property title : String

  def self.db=(database : DB::Database)
    @@db = database
  end

  def self.db
    @@db.not_nil!
  end

  def track_view
    bag = PunchingBag.new(@@db.not_nil!)
    bag.punch("Article", id.not_nil!)
  end

  def total_views
    bag = PunchingBag.new(@@db.not_nil!)
    bag.total_hits("Article", id.not_nil!)
  end

  def self.trending(since = Time.utc - 1.week, limit = 10)
    bag = PunchingBag.new(@@db.not_nil!)
    bag.most_hit(since, limit: limit)
  end
end

The Routes

get "/articles/:id" do |env|
  if article = Article.find(env.params.url["id"].to_i64)
    article.track_view
    render "article/show.ecr"
  else
    env.redirect "/articles"
  end
end

View

To display the total view count in your view, use the following HTML:

<div class="views-count">
  Views: <%= article.total_views %>
</div>

Development

crystal spec

Contributing

1. Fork it (https://github.com/dcalixto/punching_bag/fork)
2. Create your feature branch (git checkout -b my-feature)
3. Commit your changes (git commit -am 'Add feature')
4. Push to the branch (git push origin my-feature)
5. Create a new Pull Request

Contributors

Daniel Calixto - creator and maintainer

License

MIT License. See LICENSE for details.

TODO

Run the setup as follows:

require "./punching_bag/setup"

PunchingBag::Setup.run

Output Example:

Setting up development database...
Database already exists.
Creating tables and indexes...
Punches table created or already exists.
Indexes created or already exist.
Setup completed successfully.