Imre Toth's Portfolio

Building a DSL in JavaScript Without a Build Step

2026-03-29T00:00:00Z

Building a DSL in JavaScript Without a Build Step

Every codebase eventually grows its own informal language. You start with functions like createUser(name, email, role), and before long the signature is eight arguments deep and nobody remembers what the fifth one does.

The standard fixes — options objects, builder classes, method chaining — all work, but they require you to design the API up front. Change your domain, change your schema. That rigidity is the real cost.

dsl-framework takes a different approach: instead of defining an API, you define a language, and let the execution follow from the syntax.

The Core Idea

A traditional fluent API executes as it chains:

new QueryBuilder()
  .select('name')    // executes: adds 'name' to SELECT
  .from('users')     // executes: sets table to 'users'
  .where('active')   // executes: adds WHERE clause
  .run()

dsl-framework separates recording from executing. The chain builds up a data structure — an abstract syntax tree — and nothing happens until you invoke it with ():

const factory = dslFramework();

const result = factory()
  .select('name')
  .from('users')
  .where('active')
  ();   // ← this is the trigger

That closing () collapses the chain into a plain data structure you can inspect, transform, or pass to a handler.

What the Data Looks Like

Under the hood, each dotted segment becomes a chunk in returnArrayChunks:

const result = factory().Hello.world('!').data;

console.log(result.returnArrayChunks);
// [['Hello'], ['world', '!']]

console.log(result.returnArray());
// ['Hello', 'world', '!']

Arguments attach to the command that precedes them. The structure is simple enough to traverse by hand, but the framework ships with utilities so you rarely have to.

Responding to Commands

The real power shows up when you pass a callback. The callback receives the parsed data and decides what to do with it:

const greet = factory((err, data) => {
  const loud = data.command.has('loud');
  const message = data.returnArray().join(' ');
  return loud ? message.toUpperCase() : message;
});

await greet.hello.world();        // 'hello world'
await greet.hello.world.loud();   // 'HELLO WORLD'

Notice that loud isn't a function you defined anywhere. It's just a word in the chain. The callback checks whether it appeared and branches accordingly. Adding new "keywords" to your language costs zero infrastructure.

Validating Structure

The command parser ships with logical operators for checking what's in a chain:

factory((err, data) => {
  if (!data.command.hasAnd('Task', 'Deadline')) {
    return 'incomplete';
  }

  const taskName = data.arguments('Task', 'firstArgument');
  const deadline = data.arguments('Deadline', 'firstArgument');

  return `${taskName} due ${deadline}`;
})
  .Task('Write tests')
  .Deadline('2026-04-01')
  ();

hasAnd, hasOr, hasXor — these read almost like English, which is the point. The DSL you write ends up looking like the domain it describes.

Lazy Execution as a Feature

Because the chain doesn't execute until (), you can pass a pending command between modules:

// Start a command in one place
const pending = factory().Task('Code review');

// Hand it to another module that adds context
function addPriority(cmd) {
  return cmd.priority('high');
}

// Execute later
addPriority(pending)();

This turns your DSL into a first-class value. You're not calling functions — you're constructing a command object through syntax, and shipping it wherever it needs to go.

Where It Goes From Here

dsl-framework is the foundation for two other tools in this portfolio:

Metaprogramming in JS: Building a Native Macro System — goes deeper on the Proxy engine and the macro philosophy behind it
The Architecture of Demeter-DI: Fluent Interfaces and the Law of Demeter — shows how the same pattern drives a full dependency injection container

The install is one line:

npm install dsl-framework

View on GitHub · View on NPM

Your Bash Toolset is Software Now

2026-03-22T00:00:00Z

Your Bash Toolset is Software Now

bash <(curl -sL https://github.com/tothimre/packagesh/releases/latest/download/packagesh_loader.run)
source ~/.bashrc

That's the install. No sudo. No package manager. No runtime. After that, packagesh is a function in your shell — ready to bundle and publish your own Bash tools the same way.

The Problem it Solves

Bash functions loaded into the global namespace are the fastest CLI you can have. No PATH lookup. No subprocess spawn. No runtime to boot. You call my_tool and it runs — because it is your shell.

source ~/.bashrc
my_tool --do-the-thing   # instant. it's a function.

But sharing those functions has always been awkward. Copy-paste into ~/.bashrc and it rots. git clone a dotfiles repo and you're managing a repo per machine. None of these fit the shape of "I have 30 bash functions I want everywhere, always current, zero ceremony."

packagesh fits that shape.

What it Does

Point it at a directory, tell it which functions are public:

packagesh --project=/path/to/my-tool \
    --helpable-functions="my_tool" \
    --public-functions="my_tool,my_tool_helper"

It runs the full pipeline:

1. Bundle       — collects your .sh files into one loader
2. Inject help  — bakes -h documentation into the bundle
3. Snapshot     — saves a .readable pre-mangle copy for debugging
4. Mangle       — renames private functions with random suffixes
5. Wrap         — generates a self-extracting .run installer
6. Smoke test   — runs your main command to verify the bundle works
7. Publish      — uploads to GitHub Releases (skips if unchanged or --no-push)

Output lands in dist/:

dist/
├── my_tool_loader          # mangled production bundle
├── my_tool_loader.readable # pre-mangle, for debugging
└── my_tool_loader.run      # self-extracting installer

Your users install it the same way you installed packagesh:

bash <(curl -sL https://github.com/you/my-tool/releases/latest/download/my_tool_loader.run)
source ~/.bashrc
my_tool   # it's there

Namespace Safety

Sourcing multiple Bash scripts into the same shell session causes collisions. A _helper in one tool stomps the _helper in another.

packagesh mangles every private function with a random per-bundle suffix at build time:

# source
_private_helper() { ... }

# after mangling
_private_helper_a3f9c2e1b8d47f05() { ... }

Public functions stay clean. Everything internal is isolated. Source ten bundles into the same session, nothing collides. The .readable snapshot keeps it debuggable when you need to look inside.

Idempotent Publish

The publish step normalizes the bundle before hashing — stripping the random suffixes mangling introduces — then compares against the last published hash.

Run it a hundred times. It only cuts a release when something actually changed. Safe to wire into CI on every merge:

# in your github actions workflow
- run: publish_my_tool

No noise. No 400 identical releases.

For the Monorepo

packagesh works equally well in a large org with a monorepo full of Bash utilities. Build multiple projects in one shot:

packagesh --project=/tools/linter;/tools/formatter;/tools/deployer \
    --helpable-functions="main_cmd" \
    --public-functions="main_cmd"

All bundles land in dist/ inside the first path. The platform team publishes a blessed toolset. Engineers run the .run installer once, source their bashrc, and the org's standard CLI is just there — on laptops, in CI containers, in onboarding scripts.

No wiki page saying "copy this script to /usr/local/bin." No Ansible playbook to maintain. Just a .run file and a bashrc hook.

The Meta Part

packagesh is distributed using packagesh. The installer you ran at the top of this article was built and published by the tool itself.

gst

What's Next

Part 2 covers the development loop — the transparency map that lets you iterate on live functions without rebuilding the bundle, and packagesh_shell for interactive testing inside a loaded session.

Part 3 covers vendoring: how shared utilities get bundled into your tool without becoming a dependency you manage.

View on GitHub: 311ecode/packagesh

The Architecture of Demeter-DI: Fluent Interfaces and the Law of Demeter

2026-02-16T00:00:00Z

The core philosophy of Demeter-DI is rooted in two distinct technical goals: adhering to the Law of Demeter (LoD) and providing a fluent, domain-specific language (DSL) for dependency management using the dsl-framework.

Why the Shift?

In our early technical explorations, we encountered significant bottlenecks when dealing with project scale. The shift to a pure Node.js architecture allowed us to implement:

Asynchronous FS traversal: For non-blocking dependency resolution.
Regex Buffering: To handle replacements and resolutions in memory before I/O.
Atomic Operations: Ensuring that container builds don't leave the application in a partial state.

The DSL Framework: The Engine Room

The real power behind Demeter-DI isn't just the injection; it's the dsl-framework. This allows developers to chain methods like .define(), .compose(), and .create() into a readable, expressive narrative.

By using Proxy objects, we've removed the need to manually invoke service functions with parentheses when accessing them from the container.

Core Implementation Patterns

1. Define: Constants and Parameters

The define method is procedural and functional. It isolates constants from logic, promoting readability.

const container = containerFactoryFactory
    .define('PI', 3.14)
    .define('API_URL', '[https://api.example.com](https://api.example.com)')();

2. Compose: Lazy Singletons

compose creates a small DSL within your container. It utilizes Lazy Initialization—the service is executed only once, the first time it is accessed.

// The service is evaluated only when container.myService is called the first time.
containerFactoryFactory.compose('myService', (dep1, dep2) => dep1 + dep2, ['dep1', 'dep2']);

3. Create: The Factory Pattern

Unlike compose, create evaluates every time it is called. This is essential for resource-heavy operations or scenarios where a fresh instance is required (e.g., test fixtures).

// Useful for overriding complex services in test environments
containerFactoryFactory.create('complexService', () => ['fixture', 'data']);

Architectural Benefits: The Law of Demeter

Demeter-DI enforces the principle that an object should only interact with its immediate neighbors. By managing dependencies through a container, you decouple the "how" of service creation from the "what" of service usage.

Loose Coupling: Services don't need to know how to instantiate their dependencies.
Testability: Redefining a service with .create() allows for instant mocking without touching the business logic.
Atomic Consistency: The closing function call () triggers the final container build, ensuring all links are resolved.

Conclusion

By unifying the fluent interface of the Building a DSL in JavaScript Without a Build Step with a strict DI container, we've built a tool that values developer ergonomics as much as architectural purity. It is built for a JS/TS world where clarity and performance must coexist.

Metaprogramming in JS: Building a Native Macro System

2026-02-16T00:00:00Z

Inspired by Paul Graham's “Beating the Averages” and the expressive power of Lisp macros, the dsl-framework was born from a desire to treat JavaScript code as a malleable data structure without relying on string manipulation or complex build-time annotations.

The "Git Macro" Philosophy

In Lisp, macros allow you to transform code before it executes. In JavaScript, we don't have a native macro system, but we do have Proxies. dsl-framework utilizes the Proxy object to intercept property access and function calls, effectively building an Abstract Syntax Tree (AST) in real-time as you type.

How it Works: The Proxy Engine

At the heart of the framework lies the caller Proxy (found in src/core/index.js). Every time you "dot" into a new command or "invoke" a function in the chain, the framework doesn't execute logic—it records intent.

const caller = new Proxy(callerRaw, {
  get (obj, prop) {
    // Intercepts .commandName
    state.setCommandName(prop);
    return caller; // Returns itself to allow infinite chaining
  },
  apply (target, thisArg, argumentsList) {
    // Intercepts ('arguments')
    return target(...argumentsList);
  }
});

The Execution Trigger: The Closing `()`

Unlike traditional fluent interfaces (like jQuery), where each method immediately returns a modified version of the original object or triggers an action, dsl-framework treats the entire chain as a Sequence. It silently builds up state until you tell it to stop.

How do you tell it you're finished? By invoking the chain with an empty function call: ().

First-Class Sequences: The `pendingCommand`

One of the most powerful features of this architecture is that the chain remains a live, transferable object until that final invocation. We call this a pendingCommand.

Because the Proxy keeps returning itself, you can pass a partial command across different modules, layers, or functions. This allows for incredibly terse code where different parts of your application "fill in" the data before the final execution.

// 1. Start a command in one part of your app
const pendingCommand = dsl().Task.create('Code review');

// 2. Pass it around! You can add more context later
function addMetadata(cmd) {
  return cmd.priority('high').tag('urgent');
}

const enrichedCommand = addMetadata(pendingCommand);

// 3. The closing () finally triggers the execution
const result = enrichedCommand();

This "lazy execution" turns your DSL into a first-class citizen. You aren't just calling functions; you are constructing a command object through syntax.

The Evolution of a Command

Consider the sequence: .Task.create('Code review', { due: '2023-10-05' })()

.Task: The Proxy's get trap is triggered. It stores "Task" as the current command name.
.create: The previous command ("Task") is pushed into storage, and "create" becomes the new active command.
('Code review', ...): The apply trap is triggered. It takes the arguments and attaches them to the "create" command.
(): The empty invocation triggers the end of the sequence, packaging everything into a readable data structure.

The Parser: Code as Data

The command-parser (in src/core/command-parser/index.js) provides the framework's "Macro" capabilities. Once the chain is executed, it allows you to query the structure of the sequence using logical operators:

.hasAnd('Task', 'Deadline'): Ensures the sequence contains both required elements before proceeding.
.arguments('Task', 'firstArgument'): Extracts specific data points without manual array indexing.

A Different Kind of Flexibility

Traditional JavaScript APIs often require specific parameters in a strict order. If you need to add a parameter, you change the function signature. If you need to change the order, you refactor every call site.

With dsl-framework, you are building a Domain Specific Language. The logic is entirely decoupled from the syntax. You can evolve your software naturally, adding new "keywords" to your DSL without breaking existing integrations. It provides a way to treat your code as pure data, allowing you to design APIs that adapt to your domain, rather than forcing your domain to adapt to rigid functions.

Naming and renaming things...

2026-02-07T00:00:00Z

Naming and renaming things...

Naming things is easily one of the most frustrating parts of development. I’m convinced that half of "clarity" in a project is just giving parts the right labels.

However, as codebases grow—especially now that we can generate blocks of code so quickly—things get messy fast. A standard "Search and Replace All" is too much of a sledgehammer. I wanted something more like a scalpel. Asking an LLM to rename a whole project is hit-or-miss and usually misses the architectural nuances you actually care about. I built this tool to handle the heavy lifting while keeping the codebase intact.

View on GitHub: 311ecode/deepShift

DeepShift: Precise project refactoring

DeepShift is a collection of utilities for project-wide renaming. It treats a "name" as an identity that exists across your folders, filenames, and the code itself.

Context-Aware Changes

This tool is for those moments when a name is baked into everything. If you have a directory called iDoNotKnow, a file inside it called iDoNotKnow.ts, and a variable inside that called iDoNotKnow, DeepShift handles it all at once:

Structural moves: It can shift paths deeply (like moving old/ into very/deep/new/).
Atomic updates: It renames the directory, then the files, then every variable and import reference in one go.
Syncing: It keeps the folder structure and internal logic aligned, even if you flatten or extend paths.

The Tools

deepShift The core engine. It handles global string replacements, path moves, and renames files or directories if you target them specifically. Use this for variable renames, fixing typos, or moving specific paths.

codeShift This looks for filenames that match a pattern, renames them, and then fixes every import and reference across the project. Good for renaming components (e.g., changing User.ts to Account.ts).

dirShift Specifically for directories. It renames folder structures and then runs a cleanup to fix any broken relative imports caused by the move. Useful for restructuring architectural layers, like moving utils/ to helpers/.

Comparison

Goal	Tool	Logic
Rename `userId` to `accId`	deepShift	Content only
Rename `src/auth/` to `src/identity/`	dirShift	Directory move + ref fix
Swap `utils/` for `helpers/`	dirShift	Recursive folder patterns
Rename `User.ts` to `Account.ts`	codeShift	File match + ref fix

Evolution and Performance

The first version of DeepShift was written in Bash. It was simple and had zero dependencies, but it eventually hit a wall. On projects larger than 50KB, global replacements started taking upwards of ten seconds.

I decided to rewrite it in Node.js. Since I already had a solid Bash-level test suite, porting the logic was straightforward. I kept the integration tests but gained a significant speed boost. Now, even heavy refactors happen almost instantly.

Engineering Standards

I focused on three things: Precision, Automation, and Safety.

Git Integration: It checks .gitignore and runs safety checks before touching your files.
Loop Prevention: It won't get stuck in an infinite loop trying to rename a to ab.
Cross-Platform: The logic works across both GNU sed (Linux) and BSD sed (macOS).

Imre Toth's Portfolio

Building a DSL in JavaScript Without a Build Step

Building a DSL in JavaScript Without a Build Step

The Core Idea

What the Data Looks Like

Responding to Commands

Validating Structure

Lazy Execution as a Feature

Where It Goes From Here

Your Bash Toolset is Software Now

Your Bash Toolset is Software Now

The Problem it Solves

What it Does

Namespace Safety

Idempotent Publish

For the Monorepo

The Meta Part

What's Next

The Architecture of Demeter-DI: Fluent Interfaces and the Law of Demeter

Why the Shift?

The DSL Framework: The Engine Room

Core Implementation Patterns

1. Define: Constants and Parameters

2. Compose: Lazy Singletons

3. Create: The Factory Pattern

Architectural Benefits: The Law of Demeter

Conclusion

Metaprogramming in JS: Building a Native Macro System

The "Git Macro" Philosophy

How it Works: The Proxy Engine

The Execution Trigger: The Closing ()

First-Class Sequences: The pendingCommand

The Evolution of a Command

The Parser: Code as Data

A Different Kind of Flexibility

Naming and renaming things...

Naming and renaming things...

DeepShift: Precise project refactoring

Context-Aware Changes

The Tools

Comparison

Evolution and Performance

Engineering Standards

The Execution Trigger: The Closing `()`

First-Class Sequences: The `pendingCommand`