CJS

GPT-6 Astra Costs More. Use It Where It Compounds.

Sat, 05 Sep 2026 00:00:00 GMT

GPT-6 Astra arrives with the usual headline: OpenAI's most capable model yet. The more useful detail is less flattering. It is expensive.

That changes how I think about it. Astra is not a model I would put behind every autocomplete, summary, or support reply. I would use it where a better decision, fewer retries, or one finished workflow can repay the premium.

The question is not whether Astra is smarter. It is where that intelligence compounds.

The price is the first useful signal

For API users, Astra costs $10 per million input tokens and $50 per million output tokens. GPT-5.6 Sol costs $4 and $20. Terra costs $2 and $12.

Model	Input / 1M	Output / 1M	Context	Best fit
GPT-6 Astra	$10	$50	1.05M	Hard end-to-end work
GPT-5.6 Sol	$4	$20	1.05M	Complex professional work
GPT-5.6 Terra	$2	$12	1.05M	Cost-aware general workloads

Astra is 2.5 times the token price of Sol. It does not buy a larger context window; both support 1.05 million tokens and up to 128,000 output tokens. The premium is for execution quality, not raw capacity. These figures come from OpenAI's current model comparison.

That makes “cost per token” a weak buying metric. A cheaper run that needs three retries, two human rescues, and a final rewrite may cost more than one expensive run that lands cleanly.

OpenAI says Astra used fewer output tokens and reached a lower estimated API cost per task in several evaluations, despite its higher rate. That is a vendor result, not an independent guarantee, but it points toward the right unit of measurement: the completed job.

What actually changed

Astra is built for long, multi-step work across code, browsers, research, and professional software. The model supports computer use, web and file search, code execution, MCP, skills, structured outputs, and tool calling through the Responses API.

The more interesting additions are operational. Async tool calls let the model continue useful work while a slow tool runs. Mid-turn steering lets a person correct direction without discarding completed work. Reasoning effort can also change during a conversation while the stable prompt prefix remains cacheable.

Those features matter more than another impressive chat answer. They reduce the friction of giving an agent a real job, watching it work, and changing course without starting again. OpenAI documents the behaviour and limitations in its Astra model guidance.

My take: give Astra bigger units of work

Most teams still give strong models small tasks: write a function, summarise a PDF, or produce ten ideas. Astra looks better suited to a wider boundary.

Give it the research question, source rules, spreadsheet template, final brief, and acceptance criteria. Give it the repository, the failing flow, the browser, and the tests. Let it carry context across the whole outcome.

This does not mean removing human control. It means moving the checkpoint. Review the plan before consequential actions and review the deliverable at the end, rather than supervising every small step.

For a US or UK product team, that could mean turning customer interviews, support tickets, and product data into a decision memo. For an agency, it could mean researching a client, drafting the campaign assets, and checking the final site. The value comes from fewer handoffs.

Measure one completed job

I would test Astra on 10 to 20 representative tasks before changing a production workflow. Run the same tasks with Sol or Terra and keep the human process as the baseline.

Measure five things:

total model and tool cost;
time from request to accepted result;
number of retries;
number of human interventions;
defects found during review.

A simple internal measure is:

Cost per accepted result = model cost + tool cost + review time + rework time.

Also record the completion rate without rescue. That number often explains more than a benchmark score. If Astra costs 2.5 times more per token but cuts intervention and rework by more than half, it may be the cheaper system. If the result still needs the same review and correction, use the smaller model.

How I would get more from Astra

First, state the outcome and the boundary. Include the files, tools, permissions, constraints, and definition of done. Astra follows detailed instructions well, but OpenAI also notes that it is sensitive to conflicting guidance in skills and files such as AGENTS.md. Clean context is part of model performance.

Second, choose reasoning effort by task. Use low for routine work and raise it only when the decision is hard enough to justify more latency and tokens. Astra supports low, medium, high, xhigh, and max; it does not support none.

Third, use the Responses API for tool-heavy work. Async calls and mid-turn steering are useful only when the surrounding application can preserve state, surface progress, and accept corrections safely.

Fourth, keep stable instructions at the front so prompt caching can help. When changing reasoning during a conversation, OpenAI recommends a configuration_update item instead of rewriting the request-level configuration.

Finally, create a routing rule. Use Terra for volume, Sol for difficult but bounded work, and Astra for jobs where coherence across many steps has measurable value. Do not make the most expensive model the default because it is new.

The limit is still trust

Astra's stronger computer use makes permissions more important, not less. A capable agent with a vague brief can complete the wrong job faster.

Keep approval gates for money, customer data, production changes, security-sensitive actions, and external communication. Log tool calls and preserve the evidence behind important conclusions. Better reasoning does not replace accountability.

My short version is simple: buy Astra for finished work, not impressive turns. Start with the hardest workflow you can measure, compare it against Sol and your current human process, and keep it only where the total cost falls or the result clearly improves.

Sources

GPT-6 Astra model — pricing, context and output limits, reasoning levels, supported tools and endpoints. Accessed 2026-09-05.
Compare OpenAI models — Astra, GPT-5.6 Sol, and GPT-5.6 Terra positioning and API prices. Accessed 2026-09-05.
Model guidance: GPT-6 Astra — async tool calling, mid-turn steering, prompt caching, instruction sensitivity, and reported cost-per-task behaviour. Accessed 2026-09-05.

Changing Rules Without Rebuilding the App

Wed, 31 Dec 2025 00:00:00 GMT

Some releases are expensive for reasons unrelated to code. Mobile stores and mini-app platforms add review time. Desktop clients may update slowly. Even on the web, a full deployment can be a large blast radius for changing one threshold.

Remote rules can separate a business decision from the client release cycle. The useful phrase is can separate. Doing it safely requires more than putting JSON behind an endpoint.

A small example

import { createRuleEngine, createRuleHelpers } from "rule-engine-js";

type PromotionContext = {
  user: { age: number; verified: boolean };
  order: { total: number };
};

const engine = createRuleEngine();
const rules = createRuleHelpers<PromotionContext>();

const fallbackRule = rules.and(
  rules.gte("user.age", 18),
  rules.eq("user.verified", true),
  rules.gte("order.total", 50),
);

const result = engine.evaluateExpr(fallbackRule, context);

The rule is data, so a compatible replacement can be fetched without rebuilding the app. The client still needs a known-good fallback.

Treat the rule response as a contract

A remote payload should include more than an expression:

{
  "id": "promotion-eligibility",
  "version": 17,
  "schemaVersion": 1,
  "effectiveAt": "2026-09-04T00:00:00Z",
  "expression": {
    "and": [
      { "gte": ["user.age", 18] },
      { "eq": ["user.verified", true] },
      { "gte": ["order.total", 50] }
    ]
  }
}

The client should reject unsupported schema versions, invalid operators, excessive complexity, and payloads outside their validity window. Cache only a validated rule.

If fetching fails, choose the fallback based on risk:

eligibility for a cosmetic promotion may fail closed or use the bundled rule;
security and payment decisions should be enforced by the server;
stale rules should have an explicit maximum age;
a last-known-good rule should never be overwritten by an invalid response.

Roll out rules like releases

A rule change skips an app rebuild, but it is still a production change. Give it the same basics:

validate against a schema;
replay representative and boundary fixtures;
evaluate in shadow mode when possible;
activate for a small cohort;
watch decision rates and errors by version;
keep one-click rollback.

A/B tests should assign a stable cohort on the server and record both the experiment and rule versions. Otherwise support teams cannot explain why two users received different results.

Keep the authority clear

Client evaluation is useful for immediate UI feedback and offline behavior. It is not proof that an operation is allowed. A modified client can ignore the rule entirely.

For discounts, access control, fraud checks, or regulated decisions, send the same versioned context to the server and make the authoritative decision there. The client can be optimistic; the backend must be correct.

rule-engine-js v1.0.7 provides typed rule helpers, safe nested path resolution, caching, metrics, and stateful evaluation. Those features solve evaluation. Distribution, approval, compatibility, and rollback remain application concerns.

Sources: rule-engine-js repository, npm package.

My Current Neovim Workflow: Snacks, Blink, and Profiles

Wed, 27 Aug 2025 00:00:00 GMT

Editor configurations age quickly. Plugin names change, defaults move, and the workflow that looked good in a screenshot may not survive daily use.

This is the shape of my current Neovim setup, verified against the production branch of my dotfiles in September 2026.

Pick a language profile

The first decision is not a colorscheme. It is the kind of project I am opening.

The :Profile command selects core, web, go, or rust. Core covers Lua, shell, JSON, YAML, and Markdown. Other profiles enable their own LazyVim extras and use separate Mason and Treesitter data directories.

That keeps the editor's base consistent while preventing every machine from accumulating every tool.

Navigate with Snacks

Snacks now owns the high-frequency paths:

<leader>e opens the explorer;
<leader>ff finds files from the project root;
<leader>fg searches Git-tracked files;
;r greps from the current working directory;
\\ opens the buffer picker;
gd and gr use LSP definition and reference pickers;
<C-/> toggles a terminal.

Neo-tree is disabled, and Telescope is no longer the center of the setup. One picker system means fewer overlapping mappings and a more consistent preview interface.

Complete with Blink

Blink combines LSP, paths, snippets, buffer words, and tmux sources. Signature help and documentation use bordered windows; <C-y> accepts the selected item.

AI completion is optional rather than fused into the core completion path. The ai.lua and windsurf.lua specs can extend the setup, but editing and language intelligence still work without an AI provider.

That is an important boundary. Completion should degrade gracefully when a network service is unavailable.

Keep language tools explicit

Mason installs shared tools such as Stylua, Luacheck, ShellCheck, and shfmt. Profile-specific servers are added only when relevant. LSP inlay hints are disabled globally, while Lua keeps a restrained set of parameter hints.

Formatting is handled by Conform. Web formats come from LazyVim's Prettier extra; Lua uses Stylua. I prefer a clear formatter owner over an invisible chain of LSP fallbacks.

Small tools that survived

A few plugins continue to earn their place:

inc-rename for live rename feedback;
mini.bracketed for structured next/previous navigation;
Dial for numbers, dates, booleans, semantic versions, and let/const;
Outline for a symbol view;
debugprint for temporary logging with a cleanup command;
nvim-highlight-colors for CSS and Tailwind color context.

The list matters less than the filter: each tool solves friction I can name.

The full configuration lives in crafts69guy/.dotfiles. It will change again. This article records the decisions, not a promise that every plugin will remain forever.

Keeping a LazyVim Configuration Personal and Maintainable

Sun, 24 Aug 2025 00:00:00 GMT

The easy part of customizing Neovim is adding a plugin. The difficult part is remembering six months later why it exists and which defaults it replaced.

My current rule is simple: keep the distribution intact, keep overrides small, and give each piece one owner.

Prefer extension over replacement

LazyVim already supplies plugin specifications, defaults, and language extras. Local files should describe the difference between that baseline and my preferences.

For example, I use Snacks as the picker and explorer, so Neo-tree is explicitly disabled:

{
  "neo-tree.nvim",
  enabled = false,
}

That small declaration is clearer than carrying a second explorer configuration that is never used.

The same principle applies to formatting. LazyVim's Prettier extra handles common web file types; my Conform override adds Stylua for Lua rather than repeating the complete formatter table.

Use profiles for expensive language tooling

I work across web, Go, Rust, Markdown, and shell projects. Loading every language extra everywhere made startup state and Mason installations harder to reason about.

The current configuration has four profiles:

local profiles = {
  core = { label = "Core (Lua, shell, Markdown)" },
  web = { label = "Web (TypeScript, Tailwind, ESLint)" },
  go = { label = "Go" },
  rust = { label = "Rust" },
}

A :Profile command saves the selection and restarts Neovim after checking for modified buffers. Plugins are shared, while Mason and Treesitter data paths are isolated by profile. That keeps tooling focused without cloning the whole configuration.

For one-off sessions, NVIM_PROFILE can select a profile explicitly:

env NVIM_PROFILE=rust nvim

Let themes be infrastructure

The old setup hardcoded Solarized Osaka. The current one loads crafts69guy/hue-nvim from the sibling hue-theme repository when it is available.

The active mood—mua, huong, or cung—is stored outside Git under ~/.local/state/hue-theme/current. Switching colors does not dirty the dotfiles repository, and the same mood can be applied across Fish, Herdr, tmux, Ghostty, lazygit, and Neovim.

That separation is useful: the dotfiles define integration, the theme repository defines generated colors, and local state chooses the current mood.

Make custom behavior searchable

Plugin files are grouped by responsibility, custom modules live under a personal namespace, and non-obvious decisions get comments. Keymaps include descriptions so WhichKey and picker views can explain them.

When removing a plugin, search for commands, keymaps, dependencies, and module imports before deleting its spec. Configuration tends to leave small references behind.

A personal setup should feel personal at the keyboard, but boring in Git. Small files, explicit ownership, and reproducible state make experimentation cheap without making maintenance endless.

Source: current dotfiles.

Why JSON-Serializable Rules Are Worth the Constraint

Sun, 24 Aug 2025 00:00:00 GMT

Making a rule JSON-serializable sounds like an implementation detail. In practice, it changes the architecture.

A JavaScript callback can close over local variables, call a service, read the clock, or mutate state. JSON cannot do any of that. It can only describe data. That limitation is the point.

What the constraint buys you

Consider a pricing eligibility rule:

{
  "and": [
    { "eq": ["customer.tier", "gold"] },
    { "gte": ["order.total", 100] },
    { "lt": ["inventory.remaining", 10] }
  ]
}

Because the rule contains no executable code, it can cross process boundaries. The same document can be stored, reviewed, cached, compared, and sent over an API.

It also becomes possible to answer operational questions without reconstructing a deployment:

Which rule version produced this decision?
What changed between version 12 and 13?
Who approved the active version?
Can we replay yesterday's input against both versions?

Those capabilities do not come from JSON alone. JSON simply makes them practical.

What the constraint takes away

Serializable rules are less expressive than a programming language. That is healthy until teams try to rebuild a programming language inside the rule format.

Custom operators are the escape hatch. Use them for stable domain concepts, not one campaign's special case. An operator such as isBusinessDay may be reusable. An operator named after a temporary promotion is business data disguised as code.

Rules should also be deterministic. Pass volatile values such as the current time, exchange rate, or feature assignment into the evaluation context. Hidden reads make replay and auditing unreliable.

const context = {
  customer,
  order,
  inventory,
  evaluatedAt: new Date().toISOString(),
  ruleVersion: 13,
};

Activation still needs engineering discipline

Moving a rule out of the application removes the application deployment. It does not remove risk.

A production rule system needs:

schema and operator validation;
maximum depth and complexity limits;
draft, review, and activation states;
immutable versions with actor and timestamp;
canary or shadow evaluation for sensitive changes;
an immediate rollback path;
metrics keyed by rule ID and version.

For authorization, fraud, lending, or pricing, the server remains authoritative. Client-side evaluation may improve feedback, but it must not become the security boundary.

Typed authoring helps

rule-engine-js v1.0.7 added typed path autocomplete:

type Context = {
  user: { age: number };
  order: { total: number };
};

const rules = createRuleHelpers<Context>();

rules.gte("user.age", 18);
rules.gt("order.total", 0);

The generic helpers catch many path and value mistakes while a rule is authored in TypeScript. Remotely supplied JSON still needs runtime validation.

Serializable rules are worthwhile when portability and controlled change matter more than unrestricted expression. The constraint is not a workaround. It is the boundary that makes the system understandable.

Sources: repository, v1.0.7 changelog.

Managing Dotfiles with Git and GNU Stow

Sat, 23 Aug 2025 00:00:00 GMT

Dotfiles begin as a few hidden files in a home directory. Over time they become a record of how a machine works: shell behavior, editor settings, Git defaults, terminal themes, and small automation scripts.

Git gives that history a home. GNU Stow turns files in a repository into symlinks at the paths applications expect.

The basic model

Suppose a repository contains:

.dotfiles/
└── .config/
    ├── fish/
    └── nvim/

Running Stow from the repository creates links under the target directory, normally the parent of the repository. The files stay versioned in .dotfiles; applications read them through ~/.config.

My repository uses a single package rooted at ~/.dotfiles:

cd ~/.dotfiles
stow -Rv .

The -R option restows the package, and -v shows what changes. Before applying an unfamiliar repository, use simulation mode:

stow -nRv .

Read the output. Do not blindly replace existing configuration.

Adopt existing files carefully

If ~/.config/nvim already exists, Stow may report a conflict. Back it up first:

mv ~/.config/nvim ~/.config/nvim.before-stow

Then restow and compare the old files deliberately. GNU Stow also has an --adopt option, but it moves existing files into the package. That is powerful and easy to misuse. Run it only with a clean Git worktree so the resulting diff shows exactly what was adopted.

Keep local state out of Git

A dotfiles repository should describe configuration, not every changing value on a machine.

My current Hue theme switcher stores the active mood under ~/.local/state/hue-theme/current. Neovim language profile selection also lives in its state directory. Secrets, caches, plugin downloads, generated histories, and machine credentials stay outside the repository.

For host differences, prefer small OS-specific files or environment variables over copying the entire configuration. The repository currently separates Fish configuration for macOS, Linux, and Windows.

Update as a transaction

A calm update loop looks like this:

cd ~/.dotfiles
git status --short
git pull --ff-only
stow -nRv .
stow -Rv .

Check the worktree before pulling because local configuration is easy to edit accidentally through a symlink. Commit intentional changes first.

My stow_setup.sh also verifies shared agent rules, checks generated Hue integrations, rebuilds Bat's theme cache when needed, and configures Tide. Those steps are specific to this repository; plain Stow does not manage generated assets or application caches.

Rollback stays understandable

To remove the managed links without deleting the repository:

cd ~/.dotfiles
stow -Dv .

Git can restore an earlier configuration, while Stow can recreate its links. Keeping those two responsibilities separate is the reason the setup remains easy to reason about.

Source: my current dotfiles, GNU Stow manual.

Neovim Without the Mystique

Sat, 23 Aug 2025 00:00:00 GMT

Neovim is a programmable text editor with Vim's editing model and a modern Lua-based configuration ecosystem. That description is accurate, but it can make the editor sound like a project you must finish before writing code.

You do not need to build an editor from scratch. You need a small editing vocabulary, a way to inspect problems, and permission to leave the rest alone.

Learn the editing model first

Vim-style editing is modal:

Normal mode is for navigation and commands.
Insert mode is for entering text.
Visual mode is for selecting text.
Command-line mode is for editor commands.

The first useful loop is small: open a file, move with h, j, k, and l, press i to edit, press Esc to return to Normal mode, then write with :w.

Add motions as you need them. w moves by word, 0 and $ move to line boundaries, gg and G move to the start and end of a file. Operators combine with motions: dw deletes a word, while ci" changes text inside quotes.

This composability matters more than memorizing a large keymap.

Start with a distribution if you want an IDE

A plain Neovim installation is intentionally sparse. A distribution such as LazyVim provides sensible defaults for completion, language servers, formatting, search, and plugin management.

That gives beginners a working environment and a real configuration to inspect. The trade-off is another layer of conventions. When a key behaves unexpectedly, check LazyVim's mapping before assuming Neovim itself is broken.

Keep the configuration boring

A healthy first configuration answers only a few questions:

Which languages do I work in?
Which formatter should run for each file type?
How do I find files, search text, and inspect diagnostics?
Which keymaps are important enough to customize?
How can I reproduce this setup on another machine?

Add plugins to solve repeated friction, not to copy a screenshot. Every plugin creates another update and compatibility surface.

Know the repair tools

Three commands cover a surprising amount of debugging:

:checkhealth
:Lazy
:LspInfo

Use :messages after an error and :verbose map <key> to find who defined a mapping. Run Neovim without your configuration when isolating startup issues:

nvim --clean

The goal is not a perfect editor. It is an editor you can understand well enough to repair.

My current setup still uses LazyVim, but it has changed repeatedly: Telescope and Neo-tree gave way to Snacks, Solarized Osaka gave way to a personal Hue theme, and language tooling is now selected through profiles. That evolution is normal. A configuration should follow the work, not preserve every early choice.

Sources: Neovim documentation, my current dotfiles.

A Practical LazyVim Setup for Web Development

Sat, 23 Aug 2025 00:00:00 GMT

A useful Neovim setup is not the one with the most plugins. It is the one where editing, navigation, diagnostics, and formatting behave predictably.

For web development, I start with LazyVim and add language support deliberately.

Install the foundation

On macOS:

brew install neovim git fd ripgrep

Confirm Neovim starts before adding configuration:

nvim --version
nvim --clean

Then follow the current LazyVim installation guide. Keep your configuration in Git from the beginning. A broken experiment is much easier to undo when the previous state is a commit rather than a memory.

Enable only the language extras you need

My current configuration always loads JSON and Markdown support. A web profile adds TypeScript, Tailwind CSS, Docker, Prisma, ESLint, and Prettier extras:

if profile.is("web") then
  vim.list_extend(spec, {
    { import = "lazyvim.plugins.extras.lang.typescript" },
    { import = "lazyvim.plugins.extras.lang.tailwind" },
    { import = "lazyvim.plugins.extras.lang.docker" },
    { import = "lazyvim.plugins.extras.lang.prisma" },
    { import = "lazyvim.plugins.extras.linting.eslint" },
    { import = "lazyvim.plugins.extras.formatting.prettier" },
  })
end

This is more maintainable than installing every language server on every machine. It also keeps the source of each default visible: LazyVim owns the baseline; local plugin files contain only deliberate overrides.

Separate responsibilities

I keep the setup split by concern:

lua/
├── config/
│   ├── lazy.lua
│   ├── keymaps.lua
│   ├── options.lua
│   └── profile.lua
└── plugins/
    ├── coding.lua
    ├── conform.lua
    ├── lsp.lua
    ├── snacks.lua
    └── treesitter.lua

Language servers provide diagnostics and code intelligence. Conform owns formatting. Snacks owns file search, grep, explorer, and terminal workflows. Blink provides completion. Clear ownership prevents two plugins from fighting over the same job.

Verify one layer at a time

After enabling a language:

open a small real project;
run :checkhealth;
inspect attached servers with :LspInfo;
confirm go-to-definition and diagnostics;
format a deliberately messy file;
restart once and repeat.

Do not debug completion, formatting, Treesitter, and LSP at the same time. Disable layers until the failure becomes obvious.

The current configuration is available in my dotfiles. Copy ideas, not the whole directory. Your formatter choices, language mix, and keymap habits are the parts that should stay personal.

Moving Business Rules Out of Application Code

Tue, 19 Aug 2025 00:00:00 GMT

A discount rule often begins as one readable if statement. Then the exceptions arrive: customer tiers, regional limits, campaign windows, minimum totals, and one-off exclusions. The problem is not conditional logic itself. The problem is that a frequently changing business decision has become tangled with application flow.

A rule engine gives that decision a boundary.

Start with the change rate

Do not move every condition into configuration. Code is still the clearest home for stable invariants and behavior tied closely to an algorithm.

Rules become useful when a decision:

changes more often than the surrounding application;
needs an audit trail or explicit version;
appears in several entry points;
must be tested against many combinations of input;
may eventually be managed outside a deployment.

Here is a small eligibility rule with rule-engine-js:

import { createRuleEngine, createRuleHelpers } from "rule-engine-js";

type CheckoutContext = {
  customer: { tier: "standard" | "gold"; active: boolean };
  order: { total: number };
};

const engine = createRuleEngine();
const rules = createRuleHelpers<CheckoutContext>();

const canUseGoldDiscount = rules.and(
  rules.eq("customer.tier", "gold"),
  rules.eq("customer.active", true),
  rules.gte("order.total", 100),
);

const result = engine.evaluateExpr(canUseGoldDiscount, {
  customer: { tier: "gold", active: true },
  order: { total: 140 },
});

console.log(result.success);

The application still owns what happens next. The rule only answers a question.

Keep actions outside the rule

A useful separation is:

collect a trusted context;
evaluate a rule;
perform the action in application code.

That means a pricing rule can decide whether an order qualifies, but it should not charge a card or write directly to a database. Side effects stay in code where authentication, idempotency, retries, and observability are easier to enforce.

JSON is a transport format, not a governance model

A serializable rule can live in a file, database, or API response:

{
  "and": [
    { "eq": ["customer.tier", "gold"] },
    { "eq": ["customer.active", true] },
    { "gte": ["order.total", 100] }
  ]
}

That flexibility is useful, but it also creates responsibility. Validate rule shape before activation. Limit rule depth and operator count. Version changes, record who approved them, and keep rollback simple. A bad configuration can break production just as effectively as bad code.

The real payoff

The main benefit is not fewer lines. It is a clearer ownership boundary: the engine handles evaluation, the rule describes a decision, and the application handles effects. Each part can change and be tested without hiding the others.

As of v1.0.7, rule-engine-js includes typed path helpers, nested path resolution, validation helpers, state-change operators, and a stateful wrapper. Start with the plain engine. Add the advanced pieces only when the problem calls for them.

Sources: rule-engine-js repository, npm package.

Refactoring Nested Conditions into Testable Rules

Tue, 19 Aug 2025 00:00:00 GMT

The worst conditional in a codebase is rarely the longest one. It is the one nobody can change confidently.

Access checks are a common example. A function starts with role checks, grows department exceptions, then absorbs account state and resource sensitivity. Shortening that function is helpful, but the real goal is to make the decision visible and testable.

Name the decision first

Before changing syntax, decide what the code is answering:

May this user read this resource?

Then define the smallest context that can answer it.

type AccessContext = {
  user: {
    active: boolean;
    role: "admin" | "member";
    department: string;
    permissions: string[];
  };
  resource: {
    department: string;
  };
};

This step exposes accidental dependencies. If a rule needs the entire request object, it is probably not isolated yet.

Express the rule

import { createRuleEngine, createRuleHelpers } from "rule-engine-js";

const engine = createRuleEngine();
const rules = createRuleHelpers<AccessContext>();

const canReadResource = rules.and(
  rules.eq("user.active", true),
  rules.or(
    rules.eq("user.role", "admin"),
    rules.and(
      rules.field.equals("user.department", "resource.department"),
      rules.in("read", "user.permissions"),
    ),
  ),
);

The helper syntax produces a serializable rule. More importantly, the branches now read like the policy they implement.

Evaluation returns a result object:

const decision = engine.evaluateExpr(canReadResource, context);

if (!decision.success) {
  throw new Error("Access denied");
}

Keep the HTTP response, logging, and other side effects outside the rule.

Test the matrix, not the implementation

Rules invite table-driven tests. Each row describes a business case rather than a branch in the old function.

const cases = [
  ["active admin", activeAdmin, true],
  ["inactive admin", inactiveAdmin, false],
  ["member in same department", sameDepartmentMember, true],
  ["member without read permission", memberWithoutRead, false],
] as const;

for (const [name, context, expected] of cases) {
  test(name, () => {
    expect(engine.evaluateExpr(canReadResource, context).success).toBe(
      expected,
    );
  });
}

Add boundary cases: missing paths, empty permission arrays, unknown roles, and malformed remote rules. Those are usually more valuable than testing the helper calls themselves.

Refactor in two passes

First, preserve behavior. Put characterization tests around the existing function, introduce the rule, and compare both results against the same fixtures.

Second, improve the policy. Remove obsolete exceptions, split unrelated decisions, and give each rule a stable name and version. Combining cleanup with migration makes regressions much harder to diagnose.

A rule engine does not make complicated policy simple. It makes the complication explicit. That is enough to improve reviews, tests, and future changes.

Source: rule-engine-js v1.0.7.