Decorators & markers

All of these are imported from @alzulejos/laranja-decorators. They are static markers — the scanner reads them at build time to shape your infrastructure. At runtime they are near-no-ops (they don't wrap or intercept your functions), so they're safe to leave in place.

npm install @alzulejos/laranja-decorators

The schedule builders rate and every are re-exported here too, so you can import them alongside @Cron. For @nestjs/schedule compatibility, the CronExpression enum, @Interval, and @Timeout are re-exported as well — so a Nest app can repoint its import at @alzulejos/laranja-decorators unchanged.

@Cron

Schedules a class method. Each @Cron becomes a scheduled function — a Lambda + EventBridge rule on AWS, a timer trigger on Azure.

function Cron(schedule: ScheduleInput): MethodDecorator
function Cron(options: CronOptions): MethodDecorator
function Cron(expression: string, options?: NestCronOptions): MethodDecorator  // @nestjs/schedule form

import { Cron, rate, CronExpression } from "@alzulejos/laranja-decorators";

export class Jobs {
  @Cron(rate(5, "minutes"))
  async refreshCache() {}

  @Cron({ schedule: "cron(0 12 * * ? *)", id: "daily-report" })
  async report() {}

  // @nestjs/schedule style — a node-cron string or CronExpression, translated for you
  @Cron("0 3 * * *", { name: "nightly", timeZone: "Europe/Lisbon" })
  async nightly() {}

  @Cron(CronExpression.EVERY_30_MINUTES)
  async sweep() {}
}

CronOptions (laranja form)

NestCronOptions (the second argument in the @nestjs/schedule form)

See Schedules → node-cron expressions for the accepted syntax and what's rejected. Nest providers resolve through DI — declare your module with workers().

cron() marker

Function-style counterpart to @Cron, for codebases that don't use classes. Registers a standalone exported function on a schedule.

function cron(schedule: ScheduleInput, handler: JobHandler): void
function cron(options: CronOptions, handler: JobHandler): void

import { cron, rate } from "@alzulejos/laranja-decorators";

export async function refreshCache() {}

cron(rate(5, "minutes"), refreshCache);
cron({ schedule: rate(1, "hour"), id: "hourly-sync" }, refreshCache);

The function's name becomes the resource id unless you pass an explicit id.

@Interval

@nestjs/schedule-compatible. Runs a method every N milliseconds; laranja lowers it to a rate(...), so the interval must be a whole number of minutes (EventBridge's 1-minute floor).

function Interval(milliseconds: number): MethodDecorator
function Interval(name: string, milliseconds: number): MethodDecorator

import { Interval } from "@alzulejos/laranja-decorators";

export class Jobs {
  @Interval(300000)          // every 5 minutes
  async poll() {}
}

@Timeout

Re-exported for @nestjs/schedule source compatibility, but a one-shot timer relative to process start has no serverless equivalent — laranja rejects it at build time with a clear message. Use @Cron or @Interval instead.

@Queue

Consumes messages from a queue. Each @Queue becomes a queue + a consumer function — SQS on AWS, an Azure Storage Queue on Azure. The handler is called once per message with the JSON-parsed body.

function Queue(options: QueueOptions): MethodDecorator

import { Queue } from "@alzulejos/laranja-decorators";

export class Workers {
  @Queue({ name: "emails", batchSize: 10 })
  async sendEmail(body: unknown) {}

  @Queue({ name: "orders.fifo", fifo: true })
  async processOrder(body: unknown) {}
}

QueueOptions

queue() marker

Function-style counterpart to @Queue.

function queue(options: QueueOptions, handler: JobHandler): void

import { queue } from "@alzulejos/laranja-decorators";

export async function sendEmail(body: unknown) {}

queue({ name: "emails", batchSize: 10 }, sendEmail);

getQueue()

The queue producer — get a handle to a declared queue and .send() messages to it. The counterpart to the @Queue / queue() consumers. Unlike the markers, this does real work at runtime (a single send call). laranja wires the access up at deploy time — the queue URL plus sqs:SendMessage on AWS, the app's managed identity on Azure — so there's nothing to configure either way.

function getQueue(name: string): LaranjaQueue

interface LaranjaQueue {
  readonly url: string;
  send(payload: unknown, options?: SendOptions): Promise<{ messageId?: string }>;
}

import { getQueue } from "@alzulejos/laranja-decorators";

await getQueue("emails").send({ to, subject });
await getQueue("orders.fifo").send(order, { groupId: order.customerId });

payload is JSON-serialized (strings are sent as-is). name is the queue's declared name; a send to an undeclared queue throws.

SendOptions

See Queues → Sending messages.

http()

Marks the HTTP app (the proxy target) in code — the only way to declare one. Export the result so the scanner can find it.

function http<T>(app: T): T

import express from "express";
import { http } from "@alzulejos/laranja-decorators";

const app = express();
export default http(app);          // or: export const api = http(app);

It returns its argument untouched — purely a static marker. Omit it for a workers-only deployment.

For NestJS, wrap your async bootstrap factory (which returns the app) instead of an app instance — see HTTP apps → NestJS:

export default http(bootstrap);    // bootstrap: () => Promise<INestApplication>

workers()

NestJS only. Declares the module laranja builds a dependency-injection context from, so class-based @Cron / @Queue providers resolve their injected dependencies at runtime on either provider (via NestFactory.createApplicationContext) instead of a bare new. The DI counterpart to http(); export it so the scanner can find it.

function workers<T>(module: T): T

import { workers } from "@alzulejos/laranja-decorators";
import { AppModule } from "./app.module";

export default workers(AppModule);   // or: export const jobs = workers(AppModule);

Pass AppModule for the whole graph, or a leaner module for a smaller cold start. You can declare several roots — each handler is bound to exactly one, and a handler in one root never boots another root's module. Required when a Nest project has class-based workers; standalone cron()/queue() functions don't need it (no DI). Returns its argument untouched — a static marker.

env()

Declares an environment variable your code needs. At runtime it just returns process.env[name]; laranja discovers each call and populates that variable on every deployed function, with the value supplied from your shell or CI at deploy time.

function env(name: string): string | undefined

import { env } from "@alzulejos/laranja-decorators";

const dbUrl = env("DATABASE_URL");

The name must be a string literal so it can be found statically. See environment variables for supplying values, the --strict flag, and per-stage usage.

Types

Related

• Cron jobs · Queues · Schedules
• HTTP apps