Hanakai

https://hanakai.org/learn
Admin
Hanakai is a unified ecosystem of Ruby projects including Hanami (a complete web framework), Dry...
Tokens:258,630
Snippets:3,328
Trust Score:5.3
Update:5 months ago
Show doc for...
Tokens:
Raw
### Provider with Prepare, Start, and Stop Lifecycle

Source: https://hanakai.org/learn/dry/dry-system/v1.2/providers

A comprehensive provider example demonstrating setup (`prepare`), runtime usage (`start`), and cleanup (`stop`) phases. It configures a database connection and manages its lifecycle.

```ruby
# system/providers/db.rb

Application.register_provider(:database) do
  prepare do
    require 'third_party/db'

    register(:database, ThirdParty::DB.configure(ENV['DB_URL']))
  end

  start do
    container[:database].establish_connection
  end

  stop do
    container[:database].close_connection
  end
end

```

--------------------------------

### Create bin/setup Script for Development Environment

Source: https://hanakai.org/learn/hanami/v2.3/upgrade-notes

A `bin/setup` script automates development environment setup, including bundle install, npm install, and database preparation. Ensure it is executable (`chmod +x bin/setup`).

```bash
#!/usr/bin/env bash
set -euo pipefail
IFS=$'\n\t'

# This script is a way to set up and keep your development environment updated
# automatically. It is meant to be idempotent so that you can run it at any
# time to get the same result. Add any new necessary setup steps to this file
# as your application evolves.

announce() {
  local bold='\033[1m'
  local reset='\033[0m'
  printf "${bold}${1}${reset}\n"
}

announce "Running bundle install..."
bundle check || bundle install

announce "\nRunning npm install..."
npm install

announce "\nPreparing the database..."
hanami db prepare

announce "\n🌸 Setup complete!"


```

--------------------------------

### Full Example: Setup, Repository, and Usage

Source: https://hanakai.org/learn/rom/v5.0/repositories/reading-simple-objects

Demonstrates setting up a ROM container, defining a user relation and repository with selector methods, and then using these methods to query and retrieve data.

```ruby
require 'rom-repository'

rom = ROM.container(:sql, 'sqlite::memory') do |config|
  config.default.connection.create_table(:users) do
    primary_key :id
    column :name, String, null: false
    column :email, String, null: false
  end

  config.relation(:users) do
    schema(infer: true)
  end
end

class UserRepo < ROM::Repository[:users]
  def query(conditions)
    users.where(conditions).to_a
  end

  def by_id(id)
    users.by_pk(id).one!
  end

  # ... etc
end

user_repo = UserRepo.new(rom)

```

```ruby
# assuming that there is already data present

user_repo.query(first_name: 'Malcolm', last_name: 'Reynolds')
#=> [ROM::Struct[User] , ROM::Struct[User], ...]

user_repo.by_id(1)
#=> {id: 1, first_name: 'Malcolm', last_name: 'Reynolds'}

```

--------------------------------

### Hanami Development Server Output Example

Source: https://hanakai.org/learn/hanami

This is an example of the output you can expect when the Hanami development server starts successfully. It indicates that the web and assets processes have started.

```text
08:14:33 web.1    | started with pid 56242
08:14:33 assets.1 | started with pid 56243
08:14:34 assets.1 | [gsg_app] [watch] build finished, watching for changes...
08:14:34 web.1    | 08:14:34 - INFO - Using Guardfile at /Users/tim/Source/scratch/gsg_app/Guardfile.
08:14:34 web.1    | 08:14:34 - INFO - Puma starting on port 2300 in development environment.
08:14:34 web.1    | 08:14:34 - INFO - Guard is now watching at '/Users/tim/Source/scratch/gsg_app'
08:14:35 web.1    | Puma starting in single mode...
08:14:35 web.1    | * Puma version: 6.4.2 (ruby 3.3.0-p0) ("The Eagle of Durango")
08:14:35 web.1    | *  Min threads: 5
08:14:35 web.1    | *  Max threads: 5
08:14:35 web.1    | *  Environment: development
08:14:35 web.1    | *          PID: 56250
08:14:35 web.1    | * Listening on http://0.0.0.0:2300
08:14:35 web.1    | * Starting control server on http://127.0.0.1:9293
08:14:35 web.1    | * Starting control server on http://[::1]:9293
08:14:35 web.1    | Use Ctrl-C to stop
```

--------------------------------

### Registering a Basic Provider

Source: https://hanakai.org/learn/dry/dry-system/v1.2/providers

Define a provider to manage a component. The `prepare` block is for setup and requiring third-party code, while `start` registers the component with the container.

```ruby
# system/providers/persistence.rb

Application.register_provider(:database) do
  prepare do
    require "third_party/db"
  end

  start do
    register(:database, ThirdParty::DB.new)
  end
end

```

--------------------------------

### Start Hanami Console

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/console

Starts the Hanami console (REPL) for your application. The prompt indicates the current environment.

```bash
$ bundle exec hanami console

bookshelf[development]>
```

--------------------------------

### Install Hanami Gem

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

Install the Hanami gem to begin creating Hanami applications.

```bash
$ gem install hanami

```

--------------------------------

### Start the Hanami Development Server

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

Run the `hanami dev` command within your project directory to start the development server and asset watcher.

```bash
$ bundle exec hanami dev
```

--------------------------------

### Options Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Illustrates the use of named options passed after the command and arguments.

```bash
$ foo generate test
generated tests - framework: minitest

```

```bash
$ foo generate test --framework=rspec
generated tests - framework: rspec

```

```bash
$ foo generate test --framework=unknown
ERROR: "foo generate test" was called with arguments "--framework=unknown"

```

--------------------------------

### Setup ROM Container with SQL and Relations

Source: https://hanakai.org/learn/rom/v5.0/repositories/writing-aggregates

Configures an in-memory SQLite database, defines `users` and `tasks` tables with a foreign key, and establishes `has_many` and `belongs_to` associations between them. This setup is required before defining repositories.

```ruby
require 'rom-repository'

rom = ROM.container(:sql, 'sqlite::memory') do |config|
  config.default.create_table(:users) do
    primary_key :id
    column :name, String, null: false
    column :email, String, null: false
  end

  config.default.create_table(:tasks) do
    primary_key :id
    foreign_key :user_id, :users
    column :title, String, null: false
  end

  config.relation(:users) do
    schema(infer: true) do
      associations do
        has_many :tasks
      end
    end
  end

  config.relation(:tasks) do
    schema(infer: true) do
      associations do
        belongs_to :user
      end
    end
  end
end

```

--------------------------------

### Execute Command with Callbacks

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/callbacks

Example output showing the execution of the 'hello' command with both 'before' and 'after' callbacks active.

```bash
$ foo hello Anton
debug: {:name=>"Anton"}
hello Anton
bye, Anton

```

--------------------------------

### Define a complete CLI application with dry-cli

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

This example demonstrates how to define multiple commands, arguments, options, and nested commands within a dry-cli application. It includes version, echo, start, stop, exec, and completion commands, along with a nested 'generate' command.

```ruby
#!/usr/bin/env ruby
require "bundler/setup"
require "dry/cli"

module Foo
  module CLI
    module Commands
      extend Dry::CLI::Registry

      class Version < Dry::CLI::Command
        desc "Print version"

        def call(*)
          puts "1.0.0"
        end
      end

      class Echo < Dry::CLI::Command
        desc "Print input"

        argument :input, desc: "Input to print"

        example [
          "             # Prints 'wuh?'",
          "hello, folks # Prints 'hello, folks'"
        ]

        def call(input: nil, **)
          if input.nil?
            puts "wuh?"
          else
            puts input
          end
        end
      end

      class Start < Dry::CLI::Command
        desc "Start Foo machinery"

        argument :root, required: true, desc: "Root directory"

        example [
          "path/to/root # Start Foo at root directory"
        ]

        def call(root:, **)
          puts "started - root: #{root}"
        end
      end

      class Stop < Dry::CLI::Command
        desc "Stop Foo machinery"

        option :graceful, type: :boolean, default: true, desc: "Graceful stop"

        def call(**options)
          puts "stopped - graceful: #{options.fetch(:graceful)}"
        end
      end

      class Exec < Dry::CLI::Command
        desc "Execute a task"

        argument :task, type: :string, required: true,  desc: "Task to be executed"
        argument :dirs, type: :array,  required: false, desc: "Optional directories"

        def call(task:, dirs: [], **)
          puts "exec - task: #{task}, dirs: #{dirs.inspect}"
        end
      end

      class Completion < Dry::CLI::Command
        desc "Generate completion"

        option :shell, default: "bash", values: %w[bash zsh]

        def call(shell:, **)
          puts "generated completion - shell: #{shell}"
        end
      end

      module Generate
        class Configuration < Dry::CLI::Command
          desc "Generate configuration"

          option :apps, type: :array, default: [], aliases: ["-a"], desc: "Generate configuration for specific apps"

          def call(apps:, **)
            puts "generated configuration for apps: #{apps.inspect}"
          end
        end

        class Test < Dry::CLI::Command
          desc "Generate tests"

          option :framework, default: "minitest", values: %w[minitest rspec]

          def call(framework:, **)
            puts "generated tests - framework: #{framework}"
          end
        end
      end

      register "version",    Version, aliases: ["v", "-v", "--version"]
      register "echo",       Echo
      register "start",      Start
      register "stop",       Stop
      register "exec",       Exec
      register "completion", Completion, hidden: true

      register "generate", aliases: ["g"] do |prefix|
        prefix.register "config", Generate::Configuration
        prefix.register "test",   Generate::Test
      end
    end
  end
end

Dry::CLI.new(Foo::CLI::Commands).call

```

--------------------------------

### Starting a Specific Provider

Source: https://hanakai.org/learn/dry/dry-system/v1.2/providers

You can start a specific provider and access its registered components. This is useful for testing or when only a subset of the application's components is needed.

```ruby
# system/application/container.rb
class Application < Dry::System::Container
  configure do |config|
    config.root = Pathname("/my/app")
  end
end

Application.start(:database)

# and now `database` becomes available
Application["database"]

```

--------------------------------

### PostgreSQL Quick Connect

Source: https://hanakai.org/learn/rom/v5.0/sql

A quick configuration example for connecting to a PostgreSQL database using a connection string and an options hash.

```ruby
opts = {
  username: 'postgres',
  password: 'postgres',
  encoding: 'UTF8'
}
config = ROM::Configuration.new(:sql, 'postgres://localhost/database_name', opts)
```

--------------------------------

### Quick Connect with MySQL2

Source: https://hanakai.org/learn/rom/v5.0/sql

Example of configuring a ROM connection for MySQL2 with specific options like encoding.

```ruby
opts = {
  encoding: 'UTF8'
}
config = ROM::Configuration.new(:sql, 'mysql2://localhost/database_name', opts)
```

--------------------------------

### Install Hanami Dependencies

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/install

Execute this command to install third-party dependencies and Hanami gems. It's usually run automatically by `hanami new`.

```bash
$ bundle exec hanami install

```

--------------------------------

### Basic Logger Setup

Source: https://hanakai.org/learn/dry/dry-logger/v1.1

Configure a basic logger that outputs to $stdout. The logger is initialized with a program name.

```ruby
logger = Dry.Logger(:my_app)

logger.info "Hello World"
# Hello World
```

--------------------------------

### Start Hanami App in Development Mode

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/dev

Execute this command in your terminal to start the Hanami application in development mode.

```bash
$ bundle exec hanami dev

```

--------------------------------

### Custom 'enqueue' Step Adapter Example

Source: https://hanakai.org/learn/dry/dry-transaction/v0.16/custom-step-adapters

An example of a custom 'enqueue' step adapter that simulates pushing an operation into a background queue. It returns the input wrapped in a `Success` monad.

```ruby
QUEUE = []

class MyStepAdapters < Dry::Transaction::StepAdapters
  register :enqueue, -> step, input, *args {
    # In a real app, this would push the operation into a background worker queue
    QUEUE << step.operation.call(input, *args)

    Dry::Monads.Success(input)
  }
end

class CreateUser
  include Dry::Transaction(container: Container, step_adapters: MyStepAdapters)

  step :create
  enqueue :send_welcome_email
end
```

--------------------------------

### Customize Provider Source with Callbacks

Source: https://hanakai.org/learn/dry/dry-system/v1.2/external-provider-sources

Customize a provider source by adding logic to its lifecycle steps using `before` and `after` callbacks. This example adds an additional registration after the provider source has started.

```ruby
module App
  class Container < Dry::System::Container
    register_provider(:exception_notifier, from: :my_gem) do
      after(:start)
        register(:my_notifier, container[:exception_notifier])
      end
    end
  end
end
```

--------------------------------

### Generated Singleton Resource Routes

Source: https://hanakai.org/learn/hanami/v2.3/routing

This is an example of the routes generated by `resource :profile`.

```text
GET     /profile        profile.show
GET     /profile/new    profile.new
POST    /profile        profile.create
GET     /profile/edit   profile.edit
PATCH   /profile        profile.update
DELETE  /profile        profile.destroy

```

--------------------------------

### Example Usage: Greeting with Name and Age

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/arguments

Demonstrates calling the `greet` command with both the required `name` and optional `age` arguments.

```bash
$ foo greet Luca 35
Hello, Luca. You are 35 years old.

```

--------------------------------

### Command Aliases Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Illustrates the use of command aliases for shorter invocation.

```bash
$ foo version
1.0.0

```

```bash
$ foo v
1.0.0

```

```bash
$ foo -v
1.0.0

```

```bash
$ foo --version
1.0.0

```

--------------------------------

### Array Options Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Shows how to use array options, which are named arguments that accept multiple comma-separated values.

```bash
$ foo generate config --apps=web,api
generated configuration for apps: ["web", "api"]

```

--------------------------------

### Render Partial Example

Source: https://hanakai.org/learn/dry/dry-view/v0.8/templates

Demonstrates how to render a partial named 'sidebar' within a template.

```html
<%= render :sidebar %>

```

--------------------------------

### Start Hanami Console

Source: https://hanakai.org/learn/hanami/v2.3/getting-started/building-an-api

Launch the interactive console for your Hanami application to interact with the database.

```bash
$ bundle exec hanami console

```

--------------------------------

### Execute Command with Specified Option

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/options

This example demonstrates executing the command and providing a valid value for the `--mode` option.

```bash
$ foo request --mode=http2
Performing a request (mode: http2)

```

--------------------------------

### Subcommands Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Lists available subcommands for a given command. Subcommands are nested commands.

```bash
$ foo generate
Commands:
  foo generate config           # Generate configuration
  foo generate test             # Generate tests


```

--------------------------------

### Subcommand Aliases Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Demonstrates aliases for subcommands, providing shorter ways to invoke nested commands.

```bash
$ foo g config
generated configuration for apps: []

```

--------------------------------

### Example Asset Directory Structure

Source: https://hanakai.org/learn/hanami/v2.3/assets

Illustrates the directory structure for multiple entry points, showing the location of compiled CSS and JavaScript bundles.

```plaintext
app/assets
├── css
│   ├── app.css
│   └── login
│       └── app.css
├── images
│   └── favicon.ico
└── js
    ├── app.js # Entry point
    └── login
        ├── app.js # Entry point
        └── resetPassword.js

```

--------------------------------

### Example Usage: Greeting with Name Only

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/arguments

Demonstrates calling the `greet` command with only the required `name` argument.

```bash
$ foo greet Luca
Hello, Luca.

```

--------------------------------

### Executing Account Command with Specified Format

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/commands-with-subcommands-and-params

This example demonstrates executing the 'account' command and providing the 'long' format argument.

```bash
$ foo account long
# Information about account in long format.

```

--------------------------------

### Executing Account Subcommand

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/commands-with-subcommands-and-params

This example shows how to execute the 'users' subcommand of the 'account' command.

```bash
$ foo account users
# Information about account users.

```

--------------------------------

### Boolean Options Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Demonstrates boolean options, which act as flags to change command behavior.

```bash
$ foo stop
stopped - graceful: true

```

```bash
$ foo stop --no-graceful
stopped - graceful: false

```

--------------------------------

### Booting and Inspecting a Slice Container

Source: https://hanakai.org/learn/hanami/app/slices

This example shows how to boot a specific slice and inspect its available components using the Hanami console. It demonstrates accessing and calling a query from the slice's container.

```ruby
bundle exec hanami console

bookshelf[development]> API::Slice.boot
=> API::Slice
bookshelf[development]> API::Slice.keys
=> ["settings",
 "actions.countries.show",
 "queries.countries.show",
 "inflector",
 "logger",
 "notifications",
 "rack.monitor",
 "routes"]

bookshelf[development]> API::Slice["queries.countries.show"].call("UA")
=> {:name=>"Ukraine", :flag=>"🇺🇦", :currency=>"UAH"}

```

--------------------------------

### Check Node.js Version

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

Confirm Node.js is installed for front-end assets. Check if `npm` is available.

```bash
$ npm --version

```

--------------------------------

### Conditional Auto-registration

Source: https://hanakai.org/learn/dry/dry-system/v1.2/component-dirs

Use a proc with `auto_register` to conditionally enable or disable auto-registration based on component properties. This example excludes components starting with 'entities'.

```ruby
config.component_dirs.add "lib" do |dir|
  dir.auto_register = proc do |component|
    !component.identifier.start_with?("entities")
  end
end

```

--------------------------------

### Example Using All Meta Tokens

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

Demonstrates a template that includes all standard meta tokens: time, progname, severity, message, and payload. This provides a detailed log entry.

```ruby
logger = Dry.Logger(:my_app,
  template: "%<time>s [%<progname>s] %<severity>s: %<message>s %<payload>s"
)

logger.warn("High memory usage", used_mb: 1024, available_mb: 512)
# 2023-10-15 14:32:00 +0000 [my_app] WARN: High memory usage used_mb=1024 available_mb=512
```

--------------------------------

### Hanami Development Server Output

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

This is an example of the output you might see when the Hanami development server starts successfully, indicating that the web and asset processes are running.

```text
08:14:33 web.1    | started with pid 56242
08:14:33 assets.1 | started with pid 56243
08:14:34 assets.1 | [gsg_app] [watch] build finished, watching for changes...
08:14:34 web.1    | 08:14:34 - INFO - Using Guardfile at /Users/tim/Source/scratch/gsg_app/Guardfile.
08:14:34 web.1    | 08:14:34 - INFO - Puma starting on port 2300 in development environment.
08:14:34 web.1    | 08:14:34 - INFO - Guard is now watching at '/Users/tim/Source/scratch/gsg_app'
08:14:35 web.1    | Puma starting in single mode...
08:14:35 web.1    | * Puma version: 6.4.2 (ruby 3.3.0-p0) ("The Eagle of Durango")
08:14:35 web.1    | *  Min threads: 5
08:14:35 web.1    | *  Max threads: 5
08:14:35 web.1    | *  Environment: development
08:14:35 web.1    | *          PID: 56250
08:14:35 web.1    | * Listening on http://0.0.0.0:2300
08:14:35 web.1    | * Starting control server on http://127.0.0.1:9293
08:14:35 web.1    | * Starting control server on http://[::1]:9293
08:14:35 web.1    | Use Ctrl-C to stop

```

--------------------------------

### Hanami Action Example

Source: https://hanakai.org/learn/hanami/v2.3/actions

Defines a basic Hanami action that handles a GET request and responds with a personalized greeting. Accesses request parameters using `request.params`.

```ruby
# app/actions/home/show.rb

module Bookshelf
  module Actions
    module Home
      class Show < Bookshelf::Action
        def handle(request, response)
          name = request.params[:name]

          response.body = "Welcome to Bookshelf #{name}!"
        end
      end
    end
  end
end

```

--------------------------------

### Conditional Memoization

Source: https://hanakai.org/learn/dry/dry-system/v1.2/component-dirs

Use a proc with `memoize` to conditionally enable or disable memoization based on component properties. This example enables memoization for components starting with 'providers'.

```ruby
config.component_dirs.add "lib" do |dir|
  dir.memoize = proc do |component|
    component.identifier.start_with?("providers")
  end
end

```

--------------------------------

### Boot and Inspect Slice Container

Source: https://hanakai.org/learn/hanami/v2.3/app/slices

Demonstrates how to boot a specific slice and inspect its available components using the Hanami console. This is useful for debugging and understanding slice dependencies.

```ruby
bundle exec hanami console

bookshelf[development]> API::Slice.boot
=> API::Slice
bookshelf[development]> API::Slice.keys
=> ["settings",
 "actions.countries.show",
 "queries.countries.show",
 "inflector",
 "logger",
 "notifications",
 "rack.monitor",
 "routes"]


```

--------------------------------

### Example .env.test file

Source: https://hanakai.org/learn/hanami/v2.3/app/settings

Defines environment-specific variables for the test environment, such as database connection strings and feature flags.

```env
$ DATABASE_URL=postgres://localhost:5432/bookshelf_test
ANALYTICS_ENABLED=false
```

--------------------------------

### Navigate and Inspect Project Structure

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

After generating the app, change into the new directory and use `tree` to view the project's file and directory structure.

```bash
$ cd bookshelf
$ tree --gitignore --filesfirst .
```

--------------------------------

### Configure Logger Based on Environment

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Dynamically configure the logger based on the environment variable `RACK_ENV`. This example shows setup for development, production (with JSON logging and filters), and test environments.

```ruby
require "dry/logger"

def setup_logger(env)
  case env
  when "development"
    Dry.Logger(:my_app,
      template: :dev,
      colorize: true,
      level: :debug
    )
  when "production"
    Dry.Logger(:my_app) do |setup|
      setup.add_backend(
        stream: "logs/production.json",
        formatter: :json,
        filters: production_filters
      )
      setup.add_backend(
        stream: "logs/errors.json",
        formatter: :json,
        filters: production_filters,
        log_if: :error?
      )
    end
  when "test"
    require "stringio"
    Dry.Logger(:my_app,
      stream: StringIO.new,
      level: :warn  # Suppress noise in tests
    )
  end
end

def production_filters
  [:password, :api_key, :secret_token, :ssn, :credit_card_number]
end

logger = setup_logger(ENV.fetch("RACK_ENV", "development"))

```

--------------------------------

### Configuring Middleware in Rack

Source: https://hanakai.org/learn/dry/dry-effects/effects/resolve

Example of how to integrate the `ProviderMiddleware` into a Rack application's configuration. This sets up the middleware to provide dependencies like `user_repo`.

```ruby
# ...some bootstrapping code ...

use ProviderMiddleware, user_repo: UserRepo.new
run Application.new

```

--------------------------------

### Launch Hanami Development Server

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/server

Use this command to start the Hanami development server locally. It automatically watches for code changes and reloads the application.

```bash
$ bundle exec hanami server

12:30:50 - INFO - Using Guardfile at bookshelf/Guardfile.
12:30:50 - INFO - Puma starting on port 2300 in development environment.
12:30:50 - INFO - Guard is now watching at 'bookshelf'
Puma starting in single mode...
* Puma version: 6.4.0 (ruby 3.2.3-p53) ("The Eagle of Durango")
*  Min threads: 5
*  Max threads: 5
*  Environment: development
*          PID: 93401
* Listening on http://0.0.0.0:2300
* Starting control server on http://127.0.0.1:9293
* Starting control server on http://[::1]:9293
Use Ctrl-C to stop

```

--------------------------------

### Boot Hanami App and List Container Keys

Source: https://hanakai.org/learn/hanami/v2.3/app/container-and-components

Boot the Hanami application in the console and list all registered component keys in the app container. This helps in understanding available components and their access keys.

```ruby
bundle exec hanami console

bookshelf[development]> Hanami.app.boot
=> Bookshelf::App

bookshelf[development]> Hanami.app.keys
=> ["notifications",
 "settings",
 "routes",
 "inflector",
 "logger",
 "rack.monitor",
 "operations.send_welcome_email",
 "renderers.welcome_email"]

```

--------------------------------

### Catch-all route for unmatched GET requests

Source: https://hanakai.org/learn/hanami/v2.3/routing

This route acts as a catch-all for any unmatched GET requests, directing them to the 'unmatched' action.

```ruby
get "/*path", to: "unmatched"
```

--------------------------------

### Get Current Environment - Hanami.env

Source: https://hanakai.org/learn/hanami/v2.3/app/environments

Use `Hanami.env` to get a symbol representing the current environment. This is useful for conditional logic.

```ruby
# HANAMI_ENV=development

Hanami.env
=> :development
```

```ruby
# HANAMI_ENV=test

Hanami.env
=> :test
```

```ruby
# HANAMI_ENV=production

Hanami.env
=> :production
```

--------------------------------

### Add Get Method to Book Repository

Source: https://hanakai.org/learn/hanami/v2.3/getting-started/building-an-api

Extends the Book repository with a `get` method to fetch a single book by its primary key.

```ruby
# app/repos/book_repo.rb

def get(id)
  books.by_pk(id).one
end
```

--------------------------------

### JRuby JDBC Connection Examples

Source: https://hanakai.org/learn/rom/v5.0/sql

Examples of JDBC connection strings for PostgreSQL, MySQL, and in-memory SQLite databases when using JRuby.

```ruby
jdbc:postgresql://username@localhost/database
```

```ruby
jdbc:mysql://localhost/database?user=root&password=root
```

```ruby
jdbc:sqlite::memory
```

--------------------------------

### Set Up Application Container and Auto-Registration

Source: https://hanakai.org/learn/dry/dry-system/v1.2/dependency-auto-injection

Configure the application container with a root directory and component directories. This setup enables auto-registration of components based on their file paths.

```ruby
require "dry/system"

class Application < Dry::System::Container
  configure do |config|
    config.root = Pathname("/my/app")
    config.component_dirs.add "lib"
  end
end
```

--------------------------------

### Install rom-sql Gem

Source: https://hanakai.org/learn/rom/v5.0/sql

Add the rom and rom-sql gems to your Gemfile to install the SQL adapter. Ensure you are using Ruby v2.3.0 or greater.

```ruby
gem 'rom',     '~> 4.0'
gem 'rom-sql', '~> 2.0'
```

--------------------------------

### Illustrative Class Structure with Dependency Injection

Source: https://hanakai.org/learn/dry/dry-auto_inject/v1.1/how-does-it-work

This example demonstrates the internal structure generated by `dry-auto_inject`, showing how dependencies are resolved and assigned during initialization.

```ruby
class MyClass
  attr_reader :users_repository

  def self.new(**args)
    deps = {
      users_repository: args[:users_repository] || MyContainer["users_repository"]
    }

    super(**deps)
  end

  def initialize(users_repository: nil)
    super()

    @users_repository = users_repository
  end
end

```

--------------------------------

### Setup ROM with ArrayAdapter

Source: https://hanakai.org/learn/rom/v5.0/advanced/build-an-adapter

Configure and set up ROM to use the registered array adapter. This involves creating a configuration, registering relations, and building the ROM container.

```ruby
configuration= ROM::Configuration.new(:array)

class Users < ROM::Relation[:array]
  def by_name(name)
    select { |user| user[:name] == name }
  end
end

configuration.register_relation(Users)

rom = ROM.container(configuration)

users = rom.gateways[:default].dataset(:users)

users << { name: 'Jane' }
users << { name: 'John' }

rom.relations[:users].by_name('Jane').to_a
# [{:name=>"Jane"}]

```

--------------------------------

### Colorized Example with Progname and Severity

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/templates

A colorized template example that applies distinct colors to the progname and severity fields for better visual distinction.

```ruby
logger = Dry.Logger(:my_app,
  template: "[<cyan>%<progname>s</cyan>] [<yellow>%<severity>s</yellow>] %<message>s %<payload>s"
)

logger.warn("Memory warning", usage: "85%")
# [my_app] [WARN] Memory warning usage="85%"
# (with colored progname and severity)
```

--------------------------------

### Basic Combine: Load User with Projects

Source: https://hanakai.org/learn/rom/v5.0/core-concepts/combines

This example demonstrates how to load a specific user along with their associated projects using `Relation#combine`. Only requested data is loaded, preventing N+1 query issues.

```ruby
users_relation.by_id(2).combine(:projects).one

```

--------------------------------

### Boot All Hanami Application Components

Source: https://hanakai.org/learn/hanami/v2.3/app

Boot the Hanami application to register all remaining components, including those provided by default Hanami providers like routes, inflector, logger, and rack.monitor.

```ruby
Hanami.boot
=> Bookshelf::App
```

```ruby
Hanami.app.keys
["settings",
 "notifications",
 "hello_world",
 "routes",
 "inflector",
 "logger",
 "rack.monitor"]
```

--------------------------------

### Basic Request Test Example

Source: https://hanakai.org/learn/hanami/v2.3/actions/testing

This is a basic example of a request test for the root path. It checks for a successful response and verifies the response body. Use request tests to verify the whole stack is behaving as expected.

```ruby
RSpec.describe "Root", type: :request do
  it "is successful" do
    # Find me in `config/routes.rb`
    get "/"

    expect(last_response).to be_successful
    expect(last_response.body).to eq("Hello from Hanami")
  end
end
```

--------------------------------

### Add dry-logger to Gemfile

Source: https://hanakai.org/learn/dry/dry-logger

To install dry-logger, add the gem to your Gemfile.

```ruby
gem "dry-logger"

```

--------------------------------

### Benchmark: Create Command vs Changeset

Source: https://hanakai.org/learn/rom/v5.0/core-concepts/commands

Performance comparison between using a direct create command and a changeset for inserting data. Commands generally show higher throughput.

```shell
=> benchmark: create command vs changeset

Warming up --------------------------------------
             command   226.000  i/100ms
           changeset   152.000  i/100ms
Calculating -------------------------------------
             command      2.238k (±10.5%) i/s -     11.300k in   5.134520s
           changeset      1.416k (±17.1%) i/s -      6.840k in   5.035512s

Comparison:
             command:     2237.6 i/s
           changeset:     1415.6 i/s - 1.58x  slower
```

--------------------------------

### Hanami Generate Help

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/generate

Displays all available Hanami generation commands and their usage.

```bash
$ bin/hanami generate --help

Commands:
  hanami generate action NAME
  hanami generate component NAME
  hanami generate migration NAME
  hanami generate operation NAME
  hanami generate part NAME
  hanami generate relation NAME
  hanami generate repo NAME
  hanami generate slice NAME
  hanami generate struct NAME
  hanami generate view NAME

```

--------------------------------

### Generated RESTful Routes (Plural)

Source: https://hanakai.org/learn/hanami/v2.3/routing

This is an example of the routes generated by `resources :books`.

```text
GET     /books          books.index
GET     /books/:id      books.show
GET     /books/new      books.new
POST    /books          books.create
GET     /books/:id/edit books.edit
PATCH   /books/:id      books.update
DELETE  /books/:id      books.destroy

```

--------------------------------

### Column Definition Syntax Examples

Source: https://hanakai.org/learn/hanami/v2.3/database/migrations

Demonstrates various ways to define columns in a 'users' table, including explicit SQL types, inferred types, and Ruby type methods.

```ruby
create_table :users do
  # column method, explicit SQL type
  column :email, "varchar(255)", null: false

  # column method, inferred SQL type: varchar(255)
  column :email, String, null: false

  # helper method, no inference, SQL type: text
  text :email, null: false

  # Ruby type method, inferred SQL type: varchar(255)
  String :email, null: false
end

```

--------------------------------

### Display Rack Middleware Stack with Arguments

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/middleware

Include the `--with-arguments` option to display the initialization arguments for each middleware in the Rack stack.

```bash
$ bundle exec hanami middleware --with-arguments

/    Dry::Monitor::Rack::Middleware (instance) args: []
/    Rack::Session::Cookie args: [{:key=>"my_app.session", :secret=>"secret", :expire_after=>31536000}]
/    Hanami::Middleware::BodyParser args: [:json]


```

--------------------------------

### Database Provider with Lifecycle Methods

Source: https://hanakai.org/learn/hanami/v2.3/app/providers

This provider manages a database connection. It uses `prepare` to require the database library and configure the connection, `start` to establish the connection, and `stop` to close it.

```ruby
# config/providers/database.rb

Hanami.app.register_provider(:database) do
  prepare do
    require "acme/db"

    register "database", Acme::DB.configure(target["settings"].database_url)
  end

  start do
    target["database"].establish_connection
  end

  stop do
    target["database"].close_connection
  end
end

```

--------------------------------

### Require rom-sql

Source: https://hanakai.org/learn/rom/v5.0/sql

Manually require the rom-sql adapter in your script after adding it to your Gemfile or installing it.

```ruby
require 'rom-sql'
```

--------------------------------

### Define and Use a Basic Schema

Source: https://hanakai.org/learn/dry/dry-schema

This example demonstrates how to define a basic schema for user parameters including required fields, optional fields, and nested structures. It also shows how to execute the schema and inspect the result, including any validation errors.

```ruby
require "dry/schema"

UserSchema = Dry::Schema.Params do
  required(:name).filled(:string)
  required(:email).filled(:string)

  required(:age).maybe(:integer)

  required(:address).hash do
    required(:street).filled(:string)
    required(:city).filled(:string)
    required(:zipcode).filled(:string)
  end
end

UserSchema.(
  name: 'Jane',
  email: 'jane@doe.org',
  address: { street: 'Street 1', city: 'NYC', zipcode: '1234' }
).inspect

# #<Dry::Schema::Result{:name=>"Jane", :email=>"jane@doe.org", :address=>{:street=>"Street 1", :city=>"NYC", :zipcode=>"1234"}} errors={:age=>["age is missing"]}>

```

--------------------------------

### Register Before and After Callbacks for a Command

Source: https://hanakai.org/learn/dry/dry-cli/v1.1/callbacks

Demonstrates two syntaxes for registering 'before' and 'after' callbacks on an existing command. The 'before' callback receives arguments, and the 'after' callback receives a hash including the command's return values.

```ruby
Foo::CLI::Commands.before("hello") { |args| puts "debug: #{args.inspect}" } # syntax 1
Foo::CLI::Commands.after "hello", &->(args) { puts "bye, #{args.fetch(:name)}" } # syntax 2

```

--------------------------------

### Configure Routes for Book Index and Show

Source: https://hanakai.org/learn/hanami/v2.3/getting-started/building-an-api

Defines the routes for the book resource, enabling both index and show actions.

```ruby
resources :books, only: [:index, :show]
```

--------------------------------

### Define an auto-registered operation

Source: https://hanakai.org/learn/dry/dry-rails/v0.7

Example of a class in 'app/operations' that will be auto-registered and accessible via the container.

```ruby
# app/operations/users/create
module Users
  class Create
  end
end
```

--------------------------------

### Parameter Sources and Access Examples

Source: https://hanakai.org/learn/hanami/v2.3/actions/parameters

Illustrates accessing parameters from different sources: path variables, query strings, and JSON request bodies. Shows direct access using symbols.

```ruby
def handle(request, response)
  # GET /books/1
  request.params[:id] # => "1"

  # GET /books?category=history&page=2
  request.params[:category] # => "history"
  request.params[:page] # => "2"

  # POST /books '{"title": "request body", "author":"json"}', Content-Type application/json
  request.params[:title] # => "request body"
  request.params[:author] #=> "json"
end

```

--------------------------------

### Initialize ROM Configuration

Source: https://hanakai.org/learn/rom/v5.0/advanced/explicit-setup

Create a ROM::Configuration object for memory adapter and define a users relation.

```ruby
configuration = ROM::Configuration.new(:memory, 'memory://test')
configuration.relation(:users)
# ... etc

```

--------------------------------

### Check Ruby Version

Source: https://hanakai.org/learn/hanami/v2.3/getting-started

Verify your Ruby installation. Hanami requires Ruby 3.1 or greater.

```bash
$ ruby --version

```

--------------------------------

### Basic File Write with dry-files

Source: https://hanakai.org/learn/dry/dry-files/v1.1

Use `Dry::Files.new` to create a file instance and `write` to save content. Intermediate directories are automatically created if they don't exist.

```ruby
# frozen_string_literal: true
require "dry/files"

files = Dry::Files.new
files.write("path/to/file", "Hello, World!") # intermediate directories are created, if missing

```

--------------------------------

### Add dry-monads to Gemfile

Source: https://hanakai.org/learn/dry/dry-monads/v1.8/getting-started

To use dry-monads, add the gem to your Gemfile and run bundle install.

```ruby
gem 'dry-monads'
```

--------------------------------

### Development Setup with Colorized Output

Source: https://hanakai.org/learn/dry/dry-logger/v1.2/examples

Configure dry-logger for development environments to achieve maximum readability with colorized output. Register a custom template for enhanced visual feedback.

```ruby
require "dry/logger"

# Register a custom colorized template
Dry::Logger.register_template(
  :dev,
  "<gray>%<time>s</gray> <cyan>[%<progname>s]</cyan> " \
  "<yellow>%<severity>s</yellow> %<message>s <blue>%<payload>s</blue>"
)

logger = Dry.Logger(:my_app,
  template: :dev,
  level: :debug
)

logger.info("Server ready", port: 3000, env: "development")
# (colorized output) 2023-10-15 14:40:00 [my_app] INFO Server ready port=3000 env="development"
```

--------------------------------

### Insert Books into Database

Source: https://hanakai.org/learn/hanami/v2.3/getting-started/building-a-web-app

Example commands to insert book records into the database using the console.

```ruby
bookshelf[development]> books_relation = app["relations.books"]
bookshelf[development]> books_relation.insert(title: "Test Driven Development", author: "Kent Beck")
bookshelf[development]> books_relation.insert(title: "Practical Object-Oriented Design in Ruby", author: "Sandi Metz")
bookshelf[development]> books_relation.insert(title: "The Pragmatic Programmer", author: "Dave Thomas and Andy Hunt")
```

--------------------------------

### Define a dependency for auto-injection

Source: https://hanakai.org/learn/dry/dry-rails/v0.7

Example of defining a dependency (HTTP client) in 'lib' and a service that uses it.

```ruby
# lib/my_app/http.rb
module MyApp
  class HTTP
    # some useful methods
  end
end
```

```ruby
# app/services/github.rb
class Github
  include MyApp::Deps[:http]

  # more useful methods
end
```

--------------------------------

### Instantiate Repository with Container

Source: https://hanakai.org/learn/rom/v5.0/repositories/quick-start

Instantiate a repository by passing the ROM container to its constructor. This provides the repository with access to all components within the container.

```ruby
user_repo = UserRepo.new(rom)

```

--------------------------------

### Invalid Coercion Error Example

Source: https://hanakai.org/learn/hanami/v2.3/app/settings

An `InvalidSettingsError` is raised if a setting's value cannot be coerced by its specified constructor.

```bash
$ ANALYTICS_ENABLED=true MAX_CART_ITEMS="not coerceable to integer" bundle exec hanami server

! Unable to load application: Hanami::Settings::InvalidSettingsError: Could not initialize settings. The following settings were invalid:

max_cart_items: invalid value for Integer(): "not coerceable to integer"

```

--------------------------------

### Required Arguments Example

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Demonstrates the behavior of required arguments. An error is thrown if a required argument is missing.

```bash
$ foo start .
started - root: .

```

```bash
$ foo start
ERROR: "foo start" was called with no arguments
Usage: "foo start ROOT"

```

--------------------------------

### MySQL2 Driver Connection String

Source: https://hanakai.org/learn/rom/v5.0/sql

The connection string pattern for the MySQL2 driver. Ensure the 'mysql2' gem is installed.

```sql
'mysql2://[user[:password]@][host][:port][/database][?param1=value1&...]'
```

--------------------------------

### Check App Preparation and Boot Status

Source: https://hanakai.org/learn/hanami/v2.3/app

Verify if the Hanami application has been prepared or booted. Initially, these will return false before any preparation or booting steps are taken.

```ruby
Hanami.app.prepared?
=> false
```

```ruby
Hanami.app.booted?
=> false
```

--------------------------------

### Install rom and rom-sql Gem

Source: https://hanakai.org/learn/rom/v5.0/getting-started/installation

Add the 'rom' and 'rom-sql' gems to your Gemfile to use ROM with an SQL database.

```ruby
gem "rom"
gem "rom-sql"

```

--------------------------------

### Using Classes from the `lib` Directory

Source: https://hanakai.org/learn/hanami/v2.3/app/container-and-components

Illustrates placing a class in the `lib` directory to make it available application-wide without container registration.

```ruby
# lib/bookshelf/slack_notifier.rb

module Bookshelf
  class SlackNotifier
    def self.notify(message)
      # ...
    end
  end
end
```

--------------------------------

### Prepare Hanami App and Check Components

Source: https://hanakai.org/learn/hanami/v2.3/app

Prepare the Hanami application, which triggers the registration of essential components like settings and notifications. After preparation, check the registered component keys.

```ruby
Hanami.prepare
=> Bookshelf::App
```

```ruby
Hanami.app.prepared?
=> true
```

```ruby
Hanami.app.keys
=> ["settings", "notifications"]
```

--------------------------------

### Install dry-rails with Rails new

Source: https://hanakai.org/learn/dry/dry-rails/v0.7

Use this command to generate a new Rails application skeleton with dry-rails pre-installed.

```bash
rails new my_app -MOPCSJT --template https://raw.githubusercontent.com/dry-rb/dry-rails/master/templates/default.rb
```

--------------------------------

### Reset Dataset Filters

Source: https://hanakai.org/learn/hanami/v2.3/database/relations

Use the `unfiltered` method to remove all default dataset filters and start with a clean slate.

```ruby
books.unfiltered.exclude(archived_at: nil)
```

--------------------------------

### Test Hanami View Directly

Source: https://hanakai.org/learn/hanami/v2.3/views/testing

Initialize the view with dependencies and call it with expected arguments. Use `.to_s` to get the rendered output as a string. Test doubles can be used for dependencies.

```ruby
module Profile
  class Show < Main::View
    include Deps[users_repo: "repos.user_repo"]

    expose :current_user

    expose :user do |id:|
      user_repo.by_id(id)
    end
  end
end
```

```erb
<%# app/templates/views/profile/show.html.erb %>

<% if current_user.id == user.id %>
  <p class="text-base">This is your profile. You can edit your data.</p>
<% else %>
  <p class="text-base">This is the profile of <%= user.name %>. You can admire it.</p>
<% end %>
```

```ruby
RSpec.describe Views::Profile::Show do
  subject(:view) { described_class.new(users_repo:) }

  let(:user_repo) { double(:user_repo) }
  let(:current_user) { double(:user, name: "Amy", id: 1) }

  context "user inspects their profile" do
    it "renders their profile" do
      allow(user_repo).to receive(:by_id).with(1).and_return(current_user)

      output = view.call(current_user:, id: 1).to_s

      expect(output).to include("This is your profile. You can edit your data.")
    end
  end

  context "user inspects someone else's profile" do
    let(:other_user) { double(:user, name: "Lena", id: 2)}

    it "renders the other user's profile" do
      allow(users_repo).to receive(:by_id).with(2).and_return(other_user)

      output = view.call(current_user:, id: 2).to_s

      expect(output).to include("This is the profile of Lena. You can admire it.")
    end
  end
end
```

--------------------------------

### Display help for a specific command

Source: https://hanakai.org/learn/dry/dry-cli/v1.1

Use the `--help` flag to get detailed information about a command, including its usage, arguments, and options. This is useful for understanding how to use individual commands.

```bash
$ foo echo --help
Command:
  foo echo

Usage:
  foo echo [INPUT]

Description:
  Print input

Arguments:
  INPUT                 # Input to print

Options:
  --help, -h                        # Print this help

Examples:
  foo echo              # Prints 'wuh?'
  foo echo hello, folks # Prints 'hello, folks'

```

--------------------------------

### Specify Console Engine

Source: https://hanakai.org/learn/hanami/v2.3/cli-commands/console

You can explicitly choose the console engine (IRB or Pry) when starting the console. IRB is the default.

```bash
$ bundle exec hanami console --engine=irb # (the default)
```

```bash
$ bundle exec hanami console --engine=pry
```

--------------------------------

### Define a basic route

Source: https://hanakai.org/learn/hanami/v2.3/routing

This is a basic route definition for a GET request to '/books/:id' that maps to the 'books.show' action.

```ruby
get "/books/:id", to: "books.show"
```

--------------------------------

### Invalid Settings Error Example

Source: https://hanakai.org/learn/hanami/v2.3/app/settings

Hanami raises `Hanami::Settings::InvalidSettingsError` if required settings are missing or cannot be coerced.

```bash
$ bundle exec hanami server

! Unable to load application: Hanami::Settings::InvalidSettingsError: Could not initialize settings. The following settings were invalid:

analytics_enabled:  cannot be coerced to false
max_cart_items: can’t convert nil into Integer

```
Tokens:
Raw