Helpers

Introduction

JCC Express MVC registers a set of global helpers when your application boots. They are available during HTTP request handling and in tinker (with the container and providers loaded).

Runtime and environment helpers

• app -> container instance
• env(key, defaultValue?) -> config/env lookup
• rootPath(path) -> resolve project file/module path helper
• tap(value, callback?)
• now(date?) -> Carbon instance
• str() -> Str utility class

HTTP context helpers

• request() -> current AppRequest (returns {} outside an HTTP request)
• response() -> current AppResponse (returns {} outside an HTTP request)
• view(view, options?, callback?)
• inertia(component, props?, option?)
• redirect(url, status?)
• back(url?)

These depend on per-request container bindings, so they are request-lifecycle helpers. request() and response() are safe to call from code that may run outside middleware (for example pagination link builders) — they return an empty object when no request is bound.

next() is not exposed as a global helper. Use the next argument in middleware and route handlers directly.

Auth and authorization helpers

• auth() -> Authentication class (Auth.attempt, Auth.apiAttempt, Auth.logout, etc.)
• Gate -> GateFacade
• can(user, ability, model?, ...args)
• authorize(user, ability, ...args)

Database helpers

• prisma() -> registered Prisma client singleton (when database.prisma.service is configured or DB_ORM=prisma)
• typeorm() -> registered TypeORM DataSource singleton (when database.typeorm.dataSource is configured or DB_ORM=typeorm)

Also available:

• bcrypt(value)
• verifyHash(value, hash)
• jwtSign(payload, secret, options?)
• jwtVerify(token, secret)

Validation and session helpers

• validate(rules, customMessages?) -> proxy to request().validate(...)
• session() -> current session accessor (jccSession)

For validation behavior/details, see ../The Basics/Validation.md.

Deferred tasks

• defer(callback) -> run a callback after the HTTP response is sent to the client

The callback executes on the finish event of the current response, so the client never waits for it.

defer(async () => {
  await Mail.to(user.email).send({ ... });
});

return res.json({ message: "Registered" });

Errors thrown inside a deferred callback are caught and logged — they do not affect the already-sent response. See Deferred-Functions.md for full details.

Events and queue helpers

• emit(event) -> dispatch framework event (Event.dispatch)
• dispatch(job) -> push job to queue (or delayed when job.delay > 0)

Example:

emit(new UserRegistered(user));
dispatch(new SendWelcomeEmailJob(user.id));

Type declarations

TypeScript picks up helper signatures from the jcc-express-mvc package types, so env(), request(), auth(), and the rest are recognized in application code.

Notes

• Helpers that rely on request bindings (request, response, validate, session, etc.) are not meaningful before HTTP middleware bootstraps those bindings.
• request() and response() catch missing bindings and return {} instead of throwing.

Summary

• Helpers are registered automatically when the application starts.
• Use request helpers for ergonomic controller and service code.
• Use emit and dispatch for events and queues.
• Use Gate, can, and authorize for policy checks.