ambler-util
Ambler Util
Follow these steps to create or extract a utility module in the utils/ directory.
When to create a utility
Create a utils/<name>.ts file when a node's defaultUtils contains:
- External dependencies — any
npm:orjsr:import (e.g.,npm:ollama,npm:marked) - Reusable logic — code that is or could be used by more than one node
- Complex implementations — functions with significant logic (error handling, retries, connection caching, multi-step operations) that clutter the node file
Simple one-liners like (msg) => console.log(msg) or () => Math.random() belong in defaultUtils directly — no need to extract them.
1. Gather requirements
Before writing, determine:
More from argenkiwi/ambler-ts
ambler-init
Initializes a new Ambler state-machine project. Use this whenever a user wants to start a new Ambler project, bootstrap a state-machine app, or set up the Ambler folder structure — even if they just say "new project" or "set up ambler" or "create ambler folder".
13ambler-walk
Creates a complete Ambler walk — the TypeScript wiring file (walks/<name>.ts) and the Markdown spec (specs/<name>.md) — and ensures all required nodes exist. Use this whenever a user wants to add a new program or flow to an Ambler project, even if they say "new walk", "add a program", "wire up these nodes", or just describe what they want the app to do.
13ambler-test
Creates a test file for an Ambler node in the nodes/ directory. Use this whenever the user wants tests for a node — including "test this node", "add tests", "write tests for X", or any time a node is created without a corresponding test file.
12ambler-spec
Creates or updates a Markdown specification file for an Ambler walk in the specs/ directory. Use this whenever a user wants to document, plan, or describe a walk — including "write a spec", "document this walk", or "plan out the nodes" — even before any code exists.
12ambler-node
Creates a new Ambler node in the nodes/ directory. Use this whenever the user wants to add a node, step, or state to an Ambler project — even if they phrase it as "add a step", "create a handler", or describe the behavior without using the word "node".
8ambler-core
Creates a new Ambler core in the cores/ directory. Use this whenever the user wants to add a core, step, or state to an Ambler project — even if they phrase it as "add a step", "create a handler", or describe the behavior without using the word "core".
4