Onyx

Macros for easier development.

Supporters ❤️

Thanks to all my patrons, I can continue working on beautiful Open Source Software! 🙏

Lauri Jutila, Alexander Maslov, Dainel Vera

You can become a patron too in exchange of prioritized support and other perks

About 👋

This shard (should be called Onyx/Onyx) includes a number of convenient macros for easier day-to-day development with the Onyx Framework. It convers almost all of its components:

• Top-level macros:
  • Env to load environment variables from .env files
  • Logger to enable Onyx.logger
  • DB to enable Onyx.db
• Onyx::HTTP macros for use with Onyx::HTTP
• Onyx::REST macros for use with Onyx::REST
• Onyx::SQL macros for use with Onyx::SQL

Installation 📥

Add this to your application's shard.yml:

dependencies:
  onyx:
    github: onyxframework/onyx
    version: ~> 0.1.2

This shard follows Semantic Versioning v2.0.0, so check releases and change the version accordingly. Please visit github.com/crystal-lang/shards to know more about Crystal shards.

Note that this shard does not have implicit dependencies for other framework components. For example, to use "onyx/http" macros, you must add onyx-http dependendency as well:

dependencies:
  onyx:
    github: onyxframework/onyx
    version: ~> 0.1.0
  onyx-http:
    github: onyxframework/http
    version: ~> 0.1.0

Usage 💻

Env

Firstly sets CRYSTAL_ENV environment variable to "development" if not set yet. Then loads other environment variables from .env files in this order, overwriting if defined multiple times:

1. .env file
2. .env.local file
3. .env.#{CRYSTAL_ENV} file
4. .env.#{CRYSTAL_ENV}.local file

It also enables .runtime_env and .buildtime_env top-level macros which raise if an environment variable is not defined.

require "onyx/env"

# At this point, all variables are loaded from .env files
#

runtime_env DATABASE_URL # Will raise on program start if DATABASE_URL variable is missing

This feature is powered by dotenv shard by @gdotdesign.

Logger

Enables using the singleton Onyx.logger instance.

require "onyx/logger"

Onyx.logger.info("Hello world!")

DEBUG [12:45:52.520 #13543] Hello world!

DB

Enables using the singleton Onyx.db instance. It raises if no DATABASE_URL environment variable is defined or the database is not reachable.

require "onyx/db"

Onyx.db.query("SELECT 1")

HTTP

Enables the singleton Onyx::HTTP instance. It automatically requires Logger and adds the following methods:

• Onyx.get, Onyx.post, Onyx.put, Onyx.patch, Onyx.delete and Onyx.options which call the according Onyx::HTTP::Router method
• Onyx.draw which calls Onyx::HTTP::Router#draw
• Onyx.listen which launches the Onyx::HTTP::Server instance

⚠️ Note: You must manually add Onyx::HTTP as a dependency in your shard.yml.

Example:

require "onyx/http"

Onyx.get "/" do |env|
  env.response << "Hello Onyx"
end

Onyx.listen

> curl http://localhost:5000
Hello Onyx

REST

Enables the singleton Onyx::HTTP instance. It automatically requires HTTP and adds Onyx.render and Onyx.renderer methods:

⚠️ Note: You must manually add Onyx::REST as a dependency in your shard.yml.

require "onyx/rest"

struct MyView
  include Onyx::REST::View

  def initialize(@foo : String)
  end

  text("foo = #{@foo}")
end

Onyx.render(:text)
# Equals to
Onyx.renderer = Onyx::REST::Renderers::Text.new

Onyx.get "/" do |env|
  env.response.view = MyView.new("bar")
end

Onyx.listen

SQL

Enables the singleton Onyx::SQL Repository instance accessible with Onyx.repo method and also adds proxy Onyx.query, Onyx.exec and Onyx.repo methods. It automatically requires Env and DB (meaning that you must have DATABASE_URL variable defined).

⚠️ Note: You must manually add Onyx::SQL as a dependency in your shard.yml.

require "onyx/sql"

class User
  include Onyx::SQL::Model

  schema users do
    pkey id : Int32
    type name : String
  end
end

users = Onyx.query(User.where(id: 42)).first?

EDA

Enables the singleton Onyx::EDA Channel instance accessible with Onyx.channel method and also adds proxy Onyx.emit, Onyx.subscribe and Onyx.unsubscribe methods. To change the channel type use Onyx.channel(:redis) macro. It automatically requires Env and requires the REDIS_URL variable defined.

⚠️ Note: You must manually add Onyx::EDA as a dependency in your shard.yml.

require "onyx/eda"

Onyx.channel(:redis)

struct MyEvent
  include Onyx::EDA::Event

  getter foo

  def initialize(@foo : String)
  end
end

Onyx.subscribe(Object, MyEvent) do |event|
  pp event.foo
end

Onyx.emit(MyEvent.new("bar"))

sleep(0.1) # As the events are async

Onyx.unsubscribe(Object)

Community 🍪

There are multiple places to talk about this particular shard and about other ones as well:

• Main Onyx Gitter chat
• Onyx Framework Gitter community
• Vlad Faust Gitter community
• Onyx Framework Twitter
• Onyx Framework Telegram channel

Support ❤️

This shard is maintained by me, Vlad Faust, a passionate developer with years of programming and product experience. I love creating Open-Source and I want to be able to work full-time on Open-Source projects.

I will do my best to answer your questions in the free communication channels above, but if you want prioritized support, then please consider becoming my patron. Your issues will be labeled with your patronage status, and if you have a sponsor tier, then you and your team be able to communicate with me in private or semi-private channels such as e-mail and Twist. There are other perks to consider, so please, don't hesistate to check my Patreon page:

You could also help me a lot if you leave a star to this GitHub repository and spread the world about Crystal and Onyx! 📣

Contributing

1. Fork it ( https://github.com/onyxframework/http/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'feat: some feature') using Angular style commits
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Vlad Faust - creator and maintainer

Licensing

This software is licensed under MIT License.