Helpers
Helpers are small functions you import and call from anywhere in your app’s code: config('app.name'), route('posts.show', { post }), now(). They save you from passing the application object around, and every one of them is fully typed: a wrong config key or route name is a compile error, not a runtime surprise.
The smallest example
Section titled “The smallest example”import { config, Controller, now, route, type HttpContext } from '@strutvane/framework'
export class HomeController extends Controller { index(ctx: HttpContext): Response { return ctx.json({ app: config('app.name'), time: now().toISOString(), posts: route('posts.index'), }) }}What you’ll see at GET /api/home:
{ "app": "My App", "time": "2026-11-14T10:00:00.000Z", "posts": "/api/posts"}Every helper at a glance
Section titled “Every helper at a glance”| Helper | Returns | Laravel equivalent | Status |
|---|---|---|---|
config(key) |
A config value, typed by your config/*.ts files |
config('app.name') |
proven (spike 12) |
route(name, params?, options?) |
The URL of a named route | route('posts.show', $post) |
proven |
now() |
The current Date, from the app’s clock |
now() |
proven |
app() |
The current application: container, config, url |
app() |
proven |
redirect() |
A redirector: .to(), .intended(), .away() |
redirect() |
proven |
abort(status, detail?) |
Never returns: stops the request with 401, 403 or 404 | abort(404) |
proven |
url.signedRoute(name, params?, { expiresIn?, oneTime? }) |
A tamper-proof URL of a named route | URL::signedRoute() |
proven (as signedRoute()) |
url.temporarySignedRoute(name, expiresAt, params?) |
A signed URL that expires | URL::temporarySignedRoute() |
proven (as temporarySignedRoute()) |
encrypt(value, options?) / decrypt(payload, options?) |
An encrypted string / the original value | encrypt() / decrypt() |
proven |
Str, Num, retry, rescue, once, Pipeline, Benchmark, Sleep, Timebox, Lottery |
Everyday utilities | the same names (Number is Num) |
coming in 0.2 |
Concurrency, Process |
Run work in parallel; run other programs | the same names | coming in 0.3 |
config(): typed settings
Section titled “config(): typed settings”config('app.name') // stringconfig('app.debug') // booleanconfig('app.env') // 'local' | 'testing' | 'staging' | 'production'config('app.nmae') // compile error: there is no such keyThe key is a dot path: the first part is the file name in config/, the rest is the path inside it. The return type comes from that file, so config('app.debug') is a boolean, never “anything”. Config is frozen after boot: you read it, you don’t change it. See Configuration.
route(): URLs from names
Section titled “route(): URLs from names”route('posts.index') // '/api/posts'route('posts.show', { post }) // '/api/posts/hello-world' (the post's slug)route('posts.show', { post: 'hello-world' }) // a plain string or number works tooroute('posts.index', {}, { query: { page: 2 } }) // '/api/posts?page=2'route('posts.index', { page: 2 }) // '/api/posts?page=2' (extra params become the query)route('posts.show', { post }, { absolute: true }) // 'http://localhost:3000/api/posts/hello-world'route('posts.shwo', { post }) // compile error: no such routeroute('posts.show') // compile error: {post} is missingPass a model and Strutvane uses the field the route binds by ({post:slug} uses the slug). absolute: true prefixes APP_URL. Full details in Routing.
now(): a clock you can freeze
Section titled “now(): a clock you can freeze”const publishedAt = now() // a Date from the app's clockawait post.update({ status: 'published' })now() reads the clock bound to ClockToken in the container. In tests, bind a fixed clock and every timestamp is predictable:
app.container.instance(ClockToken, () => new Date('2026-11-14T10:00:00Z'))Use now() instead of new Date() in app code, so tests can control time. The rate limiter and signed URLs read the same clock.
app(): the current application
Section titled “app(): the current application”import { app, ConnectionToken } from '@strutvane/framework'
const db = app().container.make(ConnectionToken)const url = app().url.route('posts.index')Prefer constructor injection (static inject) in your own classes; app() is the escape hatch for places where injection isn’t available. See Service Container.
redirect(): send the browser elsewhere, safely
Section titled “redirect(): send the browser elsewhere, safely”import { Controller, redirect, type HttpContext } from '@strutvane/framework'
export class SessionController extends Controller { afterLogin(ctx: HttpContext): Response { // Back to where the user was going (?intended=/posts/42), or /dashboard. return redirect().intended(ctx, '/dashboard') }}| Call | Goes to | When the target is unsafe |
|---|---|---|
redirect().to('/posts', 303) |
One of your own paths (status 302 by default) | Throws: a bug in your code |
redirect().intended(ctx, '/dashboard') |
The intended query value, if it’s a same-site path |
Falls back to /dashboard quietly |
redirect().away('https://billing.example.com') |
Another site, on purpose (http or https only) | Throws for anything that isn’t a full http(s) URL |
What you’ll see: status 302 (or the one you passed) with a Location header.
Why so strict? An open redirect (your site sending people anywhere a link says) is a classic phishing tool. to() and intended() accept only same-site paths, and catch tricks like //evil.com, /\evil.com and /%2F%2Fevil.com. Leaving your site is always the explicit away().
abort(): stop right here
Section titled “abort(): stop right here”import { abort } from '@strutvane/framework'
if (post.status !== 'published') abort(404, 'No such post.')abort() throws, so code after it never runs. The exception handler turns it into a problem+json response:
| Call | Status | code |
|---|---|---|
abort(401) |
401 | unauthenticated |
abort(403, 'Only editors may do this.') |
403 | forbidden |
abort(404, 'No such post.') |
404 | not_found |
For other statuses, throw an HttpError (see Responses).
url.signedRoute() and url.temporarySignedRoute(): links nobody can change
Section titled “url.signedRoute() and url.temporarySignedRoute(): links nobody can change”A signed URL carries a signature made with your APP_KEY. Change any part of it (the id, the expiry) and the signature no longer matches. Use them for “unsubscribe” links, downloads, or anything you email.
import { Controller, url, type HttpContext } from '@strutvane/framework'
export class NewsletterController extends Controller { unsubscribeLink(ctx: HttpContext): Response { const user = ctx.requireUser() const in24Hours = new Date(Date.now() + 24 * 60 * 60 * 1000) return ctx.json({ link: url.temporarySignedRoute('newsletter.unsubscribe', in24Hours, { user: user.id }) }) }}Protect the target route with the signed middleware:
Route.get('/newsletter/unsubscribe/{user}', [NewsletterController, 'unsubscribe']).name('newsletter.unsubscribe').middleware('signed'),What you’ll see: the link works until it expires. A changed link answers 403 invalid_signature (“This link is not valid. It may have been changed or copied incompletely.”), an expired one 403 signature_expired (“This link has expired. Ask for a new one.”). See Routing.
One signer for every link. Signed routes, the sign-in package’s email verification and password reset links, and storage’s temporary file URLs all use the same framework signer: an HMAC over the path, the sorted query string, the expiry and a purpose (what the link is for), so a link made for one job can’t be reused for another. Every bad or expired link, of any kind, answers the same two codes.
One keyring for every key. Nothing uses APP_KEY directly. Each feature asks the keyring for its own key, derived from APP_KEY and the feature’s purpose (HKDF-SHA256), and old keys in APP_PREVIOUS_KEYS are still accepted after node strut key:rotate, so rotating the key doesn’t break links already sent.
encrypt() and decrypt()
Section titled “encrypt() and decrypt()”import { decrypt, encrypt } from '@strutvane/framework'
const sealed = encrypt({ iban: 'DE89 3704 0044 0532 0130 00' }, { purpose: 'billing' })const original = decrypt(sealed, { purpose: 'billing' }) // unknown: check its shape before use- Values are encrypted with AES-256-GCM using your
APP_KEY; tampering is detected. purposemust match when decrypting, so a value encrypted for one job can’t be replayed in another.- After
node strut key:rotate, the old key moves toAPP_PREVIOUS_KEYS, so values encrypted earlier still decrypt. - A tampered or foreign value throws
DecryptError: “The value could not be decrypted: it was tampered with, truncated, or made with another key.”
See Encryption.
How they know which app you mean
Section titled “How they know which app you mean”There is no global app object. Instead, Strutvane remembers “the current app” for the duration of each request and each node strut command, using Node’s AsyncLocalStorage (a built-in feature that follows your code across every await).
request arrives ──► app.handle(request) ──► [ current app = this app ] ──► middleware ──► controller ──► config() ✓Why go to this trouble? Because one Node process can hold several apps: every test file creates its own. With a global, test A could read test B’s config. With AsyncLocalStorage, each request only ever sees its own app.
Outside a request: app.run()
Section titled “Outside a request: app.run()”Code that runs at the top level of a file (when it’s imported), in a standalone script, or in a test runs outside any request. There’s no current app there, so the helpers stop with a clear message. Wrap the code in app.run():
import app from '../bootstrap/app.ts'import { route } from '@strutvane/framework'
await app.boot()const url = app.run(() => route('posts.index'))console.log(url)What you’ll see:
node scripts/print-routes.ts/api/postsIn a test, await app.run(async () => …) works the same way and supports await inside. With Docker, run scripts inside the container: node strut node scripts/print-routes.ts.
Coming next: the support helpers
Section titled “Coming next: the support helpers”Laravel ships a toolbox of small utilities (Str, Number, retry, once…). Strutvane’s will live in @strutvane/framework/support, built on the platform where it can (Intl for numbers, native arrays rather than a Collection class).
| Helper | What it’s for | Preview |
|---|---|---|
Str |
String helpers: slugs, case changes, limits, masking | Str.slug('Crème brûlée, again!') → 'creme-brulee-again' |
Num |
Numbers for people, using Intl (your locale and currency) |
Num.currency(1234.5) → '$1,234.50' |
retry |
Try something again a few times, waiting between tries | await retry(3, () => callPartner(), { sleepMs: 200 }) |
rescue |
Run something; return a fallback (and report) if it throws | rescue(() => parse(raw), []) |
once |
Run a function only the first time; reuse the result | const settings = once(() => loadSettings()) |
Pipeline |
Pass a value through a list of steps | await Pipeline.send(order).through([validate, price, tax]).thenReturn() |
Benchmark |
Measure how long code takes | await Benchmark.measure(() => report.build()) → milliseconds |
Sleep |
Wait, in a way tests can fake | await Sleep.for(2).seconds(); in tests Sleep.fake() returns at once |
Timebox |
Make a function always take the same time | protects sign-in from timing attacks: an unknown email takes as long as a wrong password |
Lottery |
Do something only sometimes | Lottery.odds(1, 100).winner(() => cleanUpOldFiles()).choose() |
Small: a slug and a price
Section titled “Small: a slug and a price”import { Num, Str } from '@strutvane/framework/support'
Str.slug('Hello World') // → 'hello-world'Num.currency(19.9, 'EUR') // → '€19.90' (depends on the locale)Typical: calling a flaky partner API
Section titled “Typical: calling a flaky partner API”import { retry } from '@strutvane/framework/support'import { safeFetch } from '@strutvane/framework/security'
export async function euroRate(): Promise<number> { const response = await retry(3, () => safeFetch('https://rates.example.com/eur'), { sleepMs: 500 }) return Number(JSON.parse(response.text()).rate)}Advanced: constant-time sign-in
Section titled “Advanced: constant-time sign-in”import { Timebox } from '@strutvane/framework/support'
// Every attempt takes at least 300 ms, so the response time can't reveal whether the email exists.const user = await Timebox.call(300, async () => findAndCheck(email, password))Coming in 0.3: work in parallel and run programs
Section titled “Coming in 0.3: work in parallel and run programs”Concurrency.run([...])runs several independent, CPU-heavy tasks on other threads or processes and returns all results (Laravel’sConcurrency::run). Worker tasks are modules, named liketask('reports/build', args), because a closure can’t travel to another thread; closures work only with thesyncdriver used in tests. The current team and request context are passed along explicitly. For several database or HTTP calls at once, plainPromise.all()already works today. See Concurrency.Process.run()runs another program without a shell (so nothing in an argument can become a second command), with time limits, pools, pipes and a fake for tests (Laravel’sProcess). On Windows,npmandnpxare run through Node directly, and other.cmdfiles are refused unless you pass{ windowsShell: true }. See Processes.
What about collections?
Section titled “What about collections?”Laravel’s Collection class isn’t copied. Query results are ordinary arrays, so map, filter, reduce and Object.groupBy already work, and the ORM adds a few typed helpers (pluck, keyBy, groupBy, chunk) plus cursor() / lazy() for streaming big tables. See ORM: Collections.
Common mistakes
Section titled “Common mistakes”“… was called outside a request or console command”
Section titled ““… was called outside a request or console command””✖ route() was called outside a request or console command, so there is no current app.→ Call it from a controller, middleware or command, or wrap the code in app.run(() => …) (tests: await app.run(async () => …)).Why: the helper ran when no request or command was active, for example in a constant at the top of a file:
const POSTS_URL = route('posts.index') // runs on import: too earlyFix: compute it inside a function that runs during a request, or use app.run():
function postsUrl(): string { return route('posts.index')}“There is no config value at …”
Section titled ““There is no config value at …””✖ There is no config value at "app.nmae".→ Check the key against the files in config/; the first segment is the file name (for example "app.name" reads config/app.ts).Why: a key built at runtime (from a variable) skipped the compile-time check, and it doesn’t exist.
Fix: use a literal key so TypeScript checks it, or fix the spelling.
“No route is named …”
Section titled ““No route is named …””✖ No route is named "post.show".→ Did you mean "posts.show"?Fix: use the suggested name, or run node strut route:list to see every name.
“redirect().to() was given …, which is not a same-origin path”
Section titled ““redirect().to() was given …, which is not a same-origin path””✖ redirect().to() was given "https://partner.example/page", which is not a same-origin path.→ Use redirect().away(url) for a deliberate external redirect.Why: to() only goes to your own paths.
Fix: redirect().away('https://partner.example/page') when leaving your site is intended.
My test’s timestamps are different every run
Section titled “My test’s timestamps are different every run”Why: the code uses new Date() instead of now(), so it ignores the test’s frozen clock.
Fix: use now() in app code, and bind ClockToken in the test.
Next steps
Section titled “Next steps”- Facades: typed static accessors, coming next.
- Configuration: the files
config()reads. - Routing: naming routes for
route(), and signed routes. - Service Container: what
app().containerholds.