Skip to content
GitHub

Strutvane 0.2 is still being built. These pages describe how it will work; anything marked "Coming in 0.2" doesn't exist yet. Release notes and support policy.

Helpers

View as Markdownllms.txt

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.

app/http/controllers/home.controller.ts
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"
}
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('app.name') // string
config('app.debug') // boolean
config('app.env') // 'local' | 'testing' | 'staging' | 'production'
config('app.nmae') // compile error: there is no such key

The 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('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 too
route('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 route
route('posts.show') // compile error: {post} is missing

Pass 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.

const publishedAt = now() // a Date from the app's clock
await 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.

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”
app/http/controllers/session.controller.ts
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().

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).

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.

app/http/controllers/newsletter.controller.ts
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:

routes/api.ts
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.

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.
  • purpose must 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 to APP_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.

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.

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():

scripts/print-routes.ts
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:

Terminal window
node scripts/print-routes.ts
/api/posts

In 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.

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()
import { Num, Str } from '@strutvane/framework/support'
Str.slug('Hello World') // → 'hello-world'
Num.currency(19.9, 'EUR') // → '€19.90' (depends on the locale)
app/services/exchange-rates.ts
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)
}
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’s Concurrency::run). Worker tasks are modules, named like task('reports/build', args), because a closure can’t travel to another thread; closures work only with the sync driver used in tests. The current team and request context are passed along explicitly. For several database or HTTP calls at once, plain Promise.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’s Process). On Windows, npm and npx are run through Node directly, and other .cmd files are refused unless you pass { windowsShell: true }. See Processes.

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.

“… 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 early

Fix: 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 "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 "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.