Skip to content

Commit 3bb8496

Browse files
drexeddrexed
committed
New docs attempt
1 parent bf17dd8 commit 3bb8496

3 files changed

Lines changed: 261 additions & 10 deletions

File tree

‎.github/workflows/docs.yml‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,34 @@
11
name: Docs
22
on:
3-
pull_request:
3+
push:
44
branches: [main]
5+
permissions:
6+
contents: write
57
jobs:
6-
build:
8+
deploy:
79
runs-on: ubuntu-latest
810
steps:
911
- name: Checkout code
1012
uses: actions/checkout@v5
1113
with:
1214
fetch-depth: 0
13-
- name: Set up Python
14-
uses: actions/setup-python@v2 # TODO: move to v6
15+
- name: Configure Git Credentials
16+
run: |
17+
git config user.name 'github-actions[bot]'
18+
git config user.email 'github-actions[bot]@users.noreply.github.com'
19+
- uses: actions/setup-python@v5
20+
with:
21+
python-version: 3.x
22+
- name: Set cache ID
23+
run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
24+
- name: Cache dependencies
25+
uses: actions/cache@v4
26+
with:
27+
key: mkdocs-material-${{ env.cache_id }}
28+
path: ~/.cache
29+
restore-keys: |
30+
mkdocs-material-
1531
- name: Install dependencies
16-
run: pip install --upgrade pip && pip install mkdocs mkdocs-gen-files
17-
- name: Configure Git
18-
run: git config user.name 'github-actions[bot]' && git config user.email 'github-actions[bot]@users.noreply.github.com'
19-
- name: Publish docs
20-
run: mkdocs gh-deploy
32+
run: pip install mkdocs-material
33+
- name: Deploy documentation
34+
run: mkdocs gh-deploy --force

‎docs/index.md‎

Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
# CMDx
2+
3+
Build business logic that's powerful, predictable, and chaos-free.
4+
5+
[![Version](https://img.shields.io/gem/v/cmdx)](https://rubygems.org/gems/cmdx)
6+
[![Build](https://github.com/drexed/cmdx/actions/workflows/ci.yml/badge.svg)](https://github.com/drexed/cmdx/actions/workflows/ci.yml)
7+
[![License](https://img.shields.io/github/license/drexed/cmdx)](https://github.com/drexed/cmdx/blob/main/LICENSE.txt)
8+
9+
Ditch the messy service objects. CMDx helps you design business processes with clarity and consistency—build faster, debug easier, and keep your sanity.
10+
11+
## Compose, Execute, React, Observe (CERO) pattern
12+
13+
CMDx encourages breaking business logic into composable tasks. Each task can be combined into larger workflows, executed with standardized flow control, and fully observed through logging, validations, and context.
14+
15+
🧩 **Compose** → Define small, contract-driven tasks with typed attributes, validations, and natural workflow composition.
16+
17+
⚡ **Execute** → Run tasks with clear outcomes, intentional halts, and pluggable behaviors via middlewares and callbacks.
18+
19+
🔄 **React** → Adapt to outcomes by chaining follow-up tasks, handling faults, or shaping future flows.
20+
21+
🔍 **Observe** → Capture immutable results, structured logs, and full execution chains for reliable tracing and insight.
22+
23+
## Installation
24+
25+
Add this line to your application's Gemfile:
26+
27+
```ruby
28+
gem "cmdx"
29+
```
30+
31+
And then execute:
32+
33+
```bash
34+
bundle
35+
```
36+
37+
Or install it yourself as:
38+
39+
```bash
40+
gem install cmdx
41+
```
42+
43+
## Quick Example
44+
45+
Here's how a quick 4 step process can open up a world of possibilities:
46+
47+
### 1. Compose
48+
49+
```ruby
50+
# Minimum Viable Task
51+
52+
class SendAnalyzedEmail < CMDx::Task
53+
def work
54+
user = User.find(context.user_id)
55+
MetricsMailer.analyzed(user).deliver_now
56+
end
57+
end
58+
59+
# Full Featured Task
60+
61+
class AnalyzeMetrics < CMDx::Task
62+
register :middleware, CMDx::Middlewares::Correlate, id: -> { Current.request_id }
63+
64+
on_success :track_analysis_completion!
65+
66+
required :dataset_id, type: :integer, numeric: { min: 1 }
67+
optional :analysis_type, default: "standard"
68+
69+
def work
70+
if dataset.nil?
71+
fail!("Dataset not found", code: 404)
72+
elsif dataset.unprocessed?
73+
skip!("Dataset not ready for analysis")
74+
else
75+
context.result = PValueAnalyzer.execute(dataset:, analysis_type:)
76+
context.analyzed_at = Time.now
77+
78+
SendAnalyzedEmail.execute(user_id: Current.account.manager_id)
79+
end
80+
end
81+
82+
private
83+
84+
def dataset
85+
@dataset ||= Dataset.find_by(id: dataset_id)
86+
end
87+
88+
def track_analysis_completion!
89+
dataset.update!(analysis_result_id: context.result.id)
90+
end
91+
end
92+
```
93+
94+
### 2. Execute
95+
96+
```ruby
97+
result = AnalyzeMetrics.execute(
98+
dataset_id: 123,
99+
"analysis_type" => "advanced"
100+
)
101+
```
102+
103+
### 3. React
104+
105+
```ruby
106+
if result.success?
107+
puts "Metrics analyzed at #{result.context.analyzed_at}"
108+
elsif result.skipped?
109+
puts "Skipping analyzation due to: #{result.reason}"
110+
elsif result.failed?
111+
puts "Analyzation failed due to: #{result.reason} with code #{result.metadata[:code]}"
112+
end
113+
```
114+
115+
### 4. Observe
116+
117+
```log
118+
I, [2022-07-17T18:42:37.000000 #3784] INFO -- CMDx:
119+
index=1 chain_id="018c2b95-23j4-2kj3-32kj-3n4jk3n4jknf" type="Task" class="SendAnalyzedEmail" state="complete" status="success" metadata={runtime: 347}
120+
121+
I, [2022-07-17T18:43:15.000000 #3784] INFO -- CMDx:
122+
index=0 chain_id="018c2b95-b764-7615-a924-cc5b910ed1e5" type="Task" class="AnalyzeMetrics" state="complete" status="success" metadata={runtime: 187}
123+
```
124+
125+
## Ecosystem
126+
127+
- [cmdx-rspec](https://github.com/drexed/cmdx-rspec) - RSpec test matchers
128+
129+
For backwards compatibility of certain functionality:
130+
131+
- [cmdx-i18n](https://github.com/drexed/cmdx-i18n) - 85+ translations, `v1.5.0` - `v1.6.2`
132+
- [cmdx-parallel](https://github.com/drexed/cmdx-parallel) - Parallel workflow tasks, `v1.6.1` - `v1.6.2`
133+
134+
## Contributing
135+
136+
Bug reports and pull requests are welcome on GitHub at [https://github.com/drexed/cmdx](https://github.com/drexed/cmdx). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
137+
138+
## License
139+
140+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
141+
142+
## Code of Conduct
143+
144+
Everyone interacting in the CMDx project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/drexed/cmdx/blob/main/CODE_OF_CONDUCT.md).
145+

‎mkdocs.yml‎

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,95 @@
11
site_name: CMDx
22
site_url: https://drexed.github.io/cmdx/
3-
theme: readthedocs
3+
site_description: Build business logic that's powerful, predictable, and chaos-free.
4+
site_author: drexed
5+
repo_name: drexed/cmdx
6+
repo_url: https://github.com/drexed/cmdx
7+
edit_uri: edit/main/docs/
8+
9+
theme:
10+
name: material
11+
palette:
12+
# Palette toggle for light mode
13+
- media: "(prefers-color-scheme: light)"
14+
scheme: default
15+
primary: indigo
16+
accent: indigo
17+
toggle:
18+
icon: material/brightness-7
19+
name: Switch to dark mode
20+
# Palette toggle for dark mode
21+
- media: "(prefers-color-scheme: dark)"
22+
scheme: slate
23+
primary: indigo
24+
accent: indigo
25+
toggle:
26+
icon: material/brightness-4
27+
name: Switch to light mode
28+
features:
29+
- navigation.instant
30+
- navigation.tracking
31+
- navigation.tabs
32+
- navigation.sections
33+
- navigation.expand
34+
- navigation.top
35+
- search.suggest
36+
- search.highlight
37+
- content.code.copy
38+
- content.code.annotate
39+
40+
markdown_extensions:
41+
- admonition
42+
- pymdownx.details
43+
- pymdownx.superfences
44+
- pymdownx.highlight:
45+
anchor_linenums: true
46+
line_spans: __span
47+
pygments_lang_class: true
48+
- pymdownx.inlinehilite
49+
- pymdownx.snippets
50+
- pymdownx.tabbed:
51+
alternate_style: true
52+
- tables
53+
- attr_list
54+
- md_in_html
55+
- toc:
56+
permalink: true
57+
58+
plugins:
59+
- search
60+
61+
nav:
62+
- Home: index.md
63+
- Getting Started: getting_started.md
64+
- Basics:
65+
- Setup: basics/setup.md
66+
- Execution: basics/execution.md
67+
- Context: basics/context.md
68+
- Chain: basics/chain.md
69+
- Interruptions:
70+
- Halt: interruptions/halt.md
71+
- Faults: interruptions/faults.md
72+
- Exceptions: interruptions/exceptions.md
73+
- Outcomes:
74+
- Result: outcomes/result.md
75+
- States: outcomes/states.md
76+
- Statuses: outcomes/statuses.md
77+
- Attributes:
78+
- Definitions: attributes/definitions.md
79+
- Naming: attributes/naming.md
80+
- Coercions: attributes/coercions.md
81+
- Validations: attributes/validations.md
82+
- Defaults: attributes/defaults.md
83+
- Transformations: attributes/transformations.md
84+
- Callbacks: callbacks.md
85+
- Middlewares: middlewares.md
86+
- Logging: logging.md
87+
- Internationalization: internationalization.md
88+
- Deprecation: deprecation.md
89+
- Workflows: workflows.md
90+
- Tips and Tricks: tips_and_tricks.md
91+
92+
extra:
93+
social:
94+
- icon: fontawesome/brands/github
95+
link: https://github.com/drexed/cmdx

0 commit comments

Comments
 (0)