@alzulejos/laranja-docs 0.2.4

package/content/guides/http-apps.md

@@ -0,0 +1,131 @@
+---
+title: HTTP apps
+description: Deploy your HTTP app behind a public HTTPS endpoint.
+order: 1
+---
+
+# HTTP apps
+
+laranja deploys your whole HTTP app as a single proxy Lambda behind a public
+[Function URL](../reference/what-gets-deployed.md#http-app--proxy-lambda--function-url).
+laranja supports **Express** and **NestJS**.
+
+## Declaring your app (the `http()` marker)
+
+The code-first way: mark your app with the
+[`http()`](../reference/decorators-and-markers.md#http) marker and export it.
+laranja finds it by scanning your code — there's nothing to configure.
+
+```ts
+// src/app.ts
+import express from "express";
+import { http } from "@alzulejos/laranja-decorators";
+
+const app = express();
+app.use(express.json());
+
+app.get("/", (_req, res) => res.json({ ok: true }));
+app.post("/users", (req, res) => res.status(201).json(req.body));
+
+export default http(app);          // or: export const api = http(app);
+```
+
+`http()` returns the app untouched — it's a static marker, not a wrapper, so it
+has no runtime effect. That's all you need: every route you register is served by
+the deployed proxy. The marker is the only way to declare an HTTP app — there's
+exactly one per project, and it must be exported so the scanner can find it.
+
+## NestJS
+
+Nest apps work the same way, with one difference: a Nest app only exists after an
+async `NestFactory.create(...)`, so instead of a ready app object you wrap your
+**bootstrap function** and have it `return` the app:
+
+```ts
+// src/main.ts
+import { NestFactory } from "@nestjs/core";
+import { http } from "@alzulejos/laranja-decorators";
+import { AppModule } from "./app.module";
+
+export async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  // configure however you like — pipes, guards, middleware, raw body, cookies…
+  app.useGlobalPipes(new ValidationPipe({ transform: true, whitelist: true }));
+  await app.listen(process.env.PORT ?? 3000);  // fine to keep for local dev
+  return app;                                  // ← the only change laranja needs
+}
+
+// Run locally with `npm run start`; skipped when laranja imports this file.
+if (require.main === module) void bootstrap();
+
+export default http(bootstrap);   // wrap the factory, not a module
+```
+
+laranja runs your `bootstrap()` verbatim, so every pipe, guard, and piece of
+middleware you configure is preserved — nothing is re-derived. You keep your
+normal Nest project (`@nestjs/platform-express`); no laranja-specific
+restructuring.
+
+Two things to know:
+
+- **Build before you deploy.** laranja packages your compiled output (`nest build`
+  → `dist/`), because Nest's dependency injection relies on the decorator metadata
+  your own TypeScript build emits. laranja deploys what you build — it doesn't run
+  your build for you — so run `nest build` yourself after every code change.
+  Deploying without a `dist/` fails with a clear message, but a **stale** `dist/`
+  (source edited since your last build) deploys silently as outdated code, so make
+  the build part of your deploy step (e.g. `nest build && laranja deploy`).
+- **Use the default Express platform.** The Fastify adapter isn't supported yet.
+
+## Routing, middleware, and `STAGE`
+
+Your app runs as-is inside Lambda. Standard Express features work — routing,
+middleware, JSON bodies, route params. The active
+[stage](./stages-and-environments.md) is available as
+`process.env.STAGE`:
+
+```ts
+app.get("/whoami", (_req, res) => res.json({ stage: process.env.STAGE }));
+```
+
+## CORS and auth
+
+The Function URL is public with permissive CORS (all origins/methods/headers).
+Handle authentication and any stricter CORS rules **inside your app**, the same
+way you would anywhere else.
+
+## Compute (memory & timeout)
+
+The HTTP proxy Lambda's memory and timeout come from
+[`compute`](../reference/config-file.md#compute) in your config — the scaffold
+default is `{ memory: 256, timeout: 30 }`, and you can override it under the `http`
+key in [`resources`](../reference/config-file.md#resources). Long-running work
+belongs in a [cron job](./cron-jobs.md) or behind a [queue](./queues.md), not a
+request.
+
+## Workers-only deployments
+
+If your HTTP API is hosted elsewhere and you only want to deploy scheduled jobs
+and queue consumers, just don't add an `http()` marker — there's nothing to set
+in config:
+
+```ts
+// laranja.config.ts
+const config: LaranjaConfig = {
+  name: "my-workers",
+  env: { LOG_LEVEL: "info" },
+};
+```
+
+With no marker, only your [`@Cron`](./cron-jobs.md) / [`@Queue`](./queues.md)
+handlers are deployed — no HTTP proxy, no Function URL.
+
+For a **workers-only Nest** app, there's no `http(bootstrap)` to build the DI
+container from, so declare your module with the
+[`workers()`](../reference/decorators-and-markers.md#workers) marker instead
+(`export default workers(AppModule)`) — see [Cron jobs → NestJS](./cron-jobs.md#nestjs).
+
+## Related
+
+- [What gets deployed](../reference/what-gets-deployed.md)
+- [Cron jobs](./cron-jobs.md) · [Queues](./queues.md)

package/content/guides/queues.md

@@ -0,0 +1,143 @@
+---
+title: Queues
+description: Process SQS messages with @Queue or queue(), including FIFO.
+order: 3
+---
+
+# Queues
+
+A queue consumer processes messages from an SQS queue. Each one becomes
+[an SQS queue plus a consumer Lambda](../reference/what-gets-deployed.md#queue--sqs-queue--consumer-lambda).
+
+## Class style — `@Queue`
+
+Decorate a method with [`@Queue`](../reference/decorators-and-markers.md#queue):
+
+```ts
+import { Queue } from "@alzulejos/laranja-decorators";
+
+export class Workers {
+  @Queue({ name: "emails", batchSize: 10 })
+  async sendEmail(body: unknown) {
+    // `body` is the JSON-parsed message
+  }
+}
+```
+
+## Function style — `queue()`
+
+```ts
+import { queue } from "@alzulejos/laranja-decorators";
+
+export async function sendEmail(body: unknown) {
+  // …
+}
+
+queue({ name: "emails", batchSize: 10 }, sendEmail);
+```
+
+## NestJS
+
+`@Queue` works on a Nest provider with injected dependencies. As with
+[cron jobs](./cron-jobs.md#nestjs), laranja resolves the consumer through your
+DI container, so declare your module once with the
+[`workers()`](../reference/decorators-and-markers.md#workers) marker
+(`export default workers(AppModule)`) and deploy your compiled `dist/` output.
+Standalone `queue()` functions don't need it.
+
+## Options
+
+| Option | Default | Description |
+|---|---|---|
+| `name` | _required_ | Queue name. A `.fifo` suffix marks a FIFO queue. |
+| `batchSize` | `10` | Max messages delivered to the consumer per invocation. |
+| `fifo` | `false` | Force a FIFO queue (or end `name` with `.fifo`). When set, laranja appends `.fifo` to `name` if you left it off. |
+
+## How messages are delivered
+
+- Your handler is invoked **once per message**, with the message **body already
+  JSON-parsed**.
+- **Partial-batch failures** are enabled: if your handler throws for one message,
+  only that message is retried — the rest of the batch is still acknowledged.
+- Consumer memory/timeout come from [`compute`](../reference/config-file.md#compute)
+  (default `{ memory: 256, timeout: 30 }`); the queue's visibility timeout is
+  derived to stay ≥ the consumer timeout (override it per queue via
+  [`resources`](../reference/config-file.md#resources)).
+
+```ts
+@Queue({ name: "orders" })
+async processOrder(body: unknown) {
+  const order = body as { id: string };
+  if (!order.id) throw new Error("bad message"); // only THIS message is retried
+  // …
+}
+```
+
+## FIFO queues
+
+End the name with `.fifo` (or set `fifo: true`) for ordered, exactly-once
+processing. Content-based deduplication is enabled automatically:
+
+```ts
+@Queue({ name: "orders.fifo", fifo: true })
+async processOrder(body: unknown) {
+  // …
+}
+```
+
+AWS requires FIFO queue names to end in `.fifo`. If you set `fifo: true` but
+leave the suffix off, laranja appends it for you — so `{ name: "orders", fifo: true }`
+deploys a queue named `orders.fifo`. The normalized name is what appears in
+`laranja plan` and in the AWS console, so there's no surprise at deploy time.
+
+## Sending messages
+
+Consuming is only half the loop — to **produce** a message, call
+[`getQueue`](../reference/decorators-and-markers.md#getqueue) with the queue's
+`name` and `.send()` a payload:
+
+```ts
+import { getQueue } from "@alzulejos/laranja-decorators";
+
+app.post("/signup", async (req, res) => {
+  await getQueue("emails").send({ to: req.body.email, template: "welcome" });
+  res.sendStatus(202);
+});
+```
+
+Objects are JSON-serialized for you (strings are sent as-is), so the consumer
+receives them already parsed — `getQueue("emails").send({ to })` on one end,
+`async sendEmail(body)` on the other.
+
+You can produce from **anywhere** in a deployed app — an HTTP route, a
+[cron job](./cron-jobs.md), or another queue's consumer fanning out. laranja
+injects each queue's URL into every function's environment at deploy and grants
+`sqs:SendMessage`, so there's no client to configure, no URL to look up, and no
+IAM to wire. It's a thin wrapper over one SQS `SendMessage` call — laranja
+provisions the infrastructure; it deliberately does **not** add a job framework
+(retries, scheduling, and job state stay with SQS and your consumer).
+
+### FIFO and options
+
+`.send()` takes a second options argument:
+
+| Option | Applies to | Description |
+|---|---|---|
+| `groupId` | FIFO (**required**) | `MessageGroupId` — messages with the same group are ordered. |
+| `dedupId` | FIFO | `MessageDeduplicationId` — only needed when content-based dedup is off. |
+| `delaySeconds` | Standard | Delay (0–900s) before the message becomes visible. Ignored by FIFO. |
+
+```ts
+// FIFO queues require a groupId — the send throws without one.
+await getQueue("orders.fifo").send(order, { groupId: order.customerId });
+```
+
+> Prefer the raw SDK? The queue URL is also emitted as a stack output after
+> deploy and visible in the AWS console — send with `@aws-sdk/client-sqs`
+> directly if you'd rather.
+
+## Related
+
+- [`@Queue` / `queue()` reference](../reference/decorators-and-markers.md#queue)
+- [What gets deployed](../reference/what-gets-deployed.md#queue--sqs-queue--consumer-lambda)
+- [Cron jobs](./cron-jobs.md)

package/content/guides/schedules.md

@@ -0,0 +1,117 @@
+---
+title: Schedules
+description: The rate() and every() builders, and raw schedule expressions.
+order: 4
+---
+
+# Schedules
+
+Schedules drive [cron jobs](./cron-jobs.md). laranja stores them in a
+**provider-neutral** form, so prefer the builders — they're portable across
+clouds. A raw expression string is available as an escape hatch.
+
+## `rate(value, unit)`
+
+"Every N units." Portable everywhere.
+
+```ts
+import { rate } from "@alzulejos/laranja-decorators";
+
+rate(5, "minutes")   // every 5 minutes
+rate(1, "hour")      // every hour
+rate(2, "days")      // every 2 days
+```
+
+- `value` must be a **positive integer** (≥ 1).
+- `unit` is one of `"minute"`, `"minutes"`, `"hour"`, `"hours"`, `"day"`,
+  `"days"` — singular or plural, your choice.
+
+## `every(unit)`
+
+Shorthand for `rate(1, unit)`. Takes a singular unit:
+
+```ts
+import { every } from "@alzulejos/laranja-decorators";
+
+every("minute")   // = rate(1, "minute")
+every("hour")     // = rate(1, "hour")
+every("day")      // = rate(1, "day")
+```
+
+## Raw AWS expressions (escape hatch)
+
+When you need something the builders can't express (e.g. "noon UTC every day"),
+pass a **wrapped** AWS schedule string — `cron(...)` or `rate(...)`:
+
+```ts
+@Cron({ schedule: "cron(0 12 * * ? *)", id: "daily-report" })  // 12:00 UTC daily
+@Cron("rate(5 minutes)")                                       // raw rate string
+```
+
+AWS cron has **six fields**: `cron(Minutes Hours Day-of-month Month Day-of-week
+Year)`.
+
+A few examples:
+
+| Expression | Meaning |
+|---|---|
+| `cron(0 12 * * ? *)` | 12:00 UTC every day |
+| `cron(0/15 * * * ? *)` | every 15 minutes |
+| `cron(0 8 ? * MON-FRI *)` | 08:00 UTC on weekdays |
+| `cron(0 0 1 * ? *)` | midnight UTC on the 1st of each month |
+
+## node-cron expressions (`@nestjs/schedule` compatibility)
+
+A **bare** (unwrapped) string is read as a standard 5- or 6-field
+[node-cron](https://github.com/kelektiv/node-cron) expression — the same syntax
+`@nestjs/schedule`'s `@Cron` takes. laranja translates it to the AWS dialect for
+you, so a Nest app can swap the import and keep its existing schedules:
+
+```ts
+@Cron("0 12 * * *")                 // noon every day
+@Cron("*/5 * * * *")                // every 5 minutes
+@Cron("0 0 * * 1-5")                // midnight on weekdays
+@Cron(CronExpression.EVERY_30_MINUTES)  // the enum works too
+```
+
+`CronExpression` (mirrored from `@nestjs/schedule`) is re-exported from
+`@alzulejos/laranja-decorators`. Translation handles the day-of-week numbering difference
+(Unix `0`=Sun → AWS `1`=Sun) and the day-of-month/day-of-week rule for you.
+
+**What can't be translated is rejected at build time — never silently rounded:**
+
+| Input | Why it's rejected |
+|---|---|
+| `"*/30 * * * * *"`, `CronExpression.EVERY_30_SECONDS` | Sub-minute — EventBridge's floor is **1 minute**. |
+| A seconds field other than `0` | Second-level offsets can't be expressed. |
+| A cron constraining **both** day-of-month and day-of-week | EventBridge requires one to be `*`. |
+
+## `@Interval(ms)`
+
+`@nestjs/schedule`'s `@Interval` is supported and lowers to a `rate(...)`. The
+interval must be a whole number of minutes (EventBridge's floor):
+
+```ts
+@Interval(300000)          // every 5 minutes  → rate(5, "minutes")
+@Interval("poll", 300000)  // named
+```
+
+> `@Timeout` (a one-shot timer relative to process start) has no serverless
+> equivalent and is rejected with a clear message — use `@Cron` or `@Interval`.
+
+## Where you can use them
+
+Anywhere a schedule is expected — the decorator or the function marker — accepts
+a builder result, a `Schedule` object, or a raw string:
+
+```ts
+@Cron(rate(5, "minutes"))                       // builder
+@Cron("rate(5 minutes)")                        // raw string
+@Cron({ schedule: every("day"), id: "nightly" })// builder + explicit id
+cron(rate(1, "hour"), refreshCache);            // function marker
+```
+
+## Related
+
+- [Cron jobs](./cron-jobs.md)
+- [`@Cron` / `cron()` reference](../reference/decorators-and-markers.md#cron)

package/content/guides/stages-and-environments.md

@@ -0,0 +1,88 @@
+---
+title: Stages & environments
+description: Run dev, staging, and prod from one codebase with --stage.
+order: 6
+---
+
+# Stages & environments
+
+A **stage** is a named environment — `dev`, `staging`, `prod`, or anything you
+like. laranja makes each stage a fully independent deployment from the same
+codebase.
+
+## Setting the stage
+
+The default stage is `dev`. Set it in config:
+
+```ts
+// laranja.config.ts
+const config: LaranjaConfig = { name: "my-api", stage: "dev" };
+```
+
+…or override it per command with `--stage` (alias `-s`):
+
+```bash
+laranja deploy --stage prod
+laranja deploy -s staging
+```
+
+The flag wins over the config value, which is why the recommended setup keeps
+`stage` at its default in config and lets each pipeline pass `--stage`.
+
+`--stage` applies to every environment-aware command: `deploy`, `plan`,
+`destroy`, `logs`, and `eject`.
+
+## Each stage is its own stack
+
+The stage is part of the **stack name** (`‹name›-‹stage›`) and every resource
+name (`‹name›-‹fn›-‹stage›`). So `--stage dev` and `--stage prod` produce two
+**independent CloudFormation stacks** that never collide — even in the same AWS
+account.
+
+```
+my-api-dev     ← laranja deploy --stage dev
+my-api-prod    ← laranja deploy --stage prod
+```
+
+## Two ways to isolate environments
+
+Both work, and they compose:
+
+1. **One account, multiple stages.** The stage suffix keeps the stacks separate.
+   Good for small projects or non-prod environments.
+2. **Separate accounts per stage.** Point each pipeline at different AWS
+   credentials (a dev account and a prod account). Here your **AWS credentials
+   are the real boundary**; the stack name can even repeat across accounts
+   without conflict.
+
+## One pipeline per stage
+
+The canonical CI/CD setup is one pipeline per environment, each running the same
+command with a different flag:
+
+```yaml
+# dev pipeline       → laranja deploy --stage dev
+# staging pipeline   → laranja deploy --stage staging
+# prod pipeline      → laranja deploy --stage prod
+```
+
+Same repo, same command — only the flag differs. No per-environment config files
+to keep in sync. Pair this with [per-stage env values](./environment-variables.md#per-stage-values)
+to supply each environment's configuration.
+
+> Consistency matters: a pipeline's `destroy`, `logs`, and `plan` must use the
+> **same `--stage`** as its `deploy`, or they'll target a different stack.
+
+## The `STAGE` env var
+
+The active stage is injected into every Lambda as `process.env.STAGE`, so your
+code can branch on it:
+
+```ts
+const isProd = process.env.STAGE === "prod";
+```
+
+## Related
+
+- [Config file](../reference/config-file.md)
+- [Environment variables](./environment-variables.md)

package/content/index.md

@@ -0,0 +1,44 @@
+---
+title: Documentation
+description: Code-first deploys for Node.js apps to your own AWS account.
+order: 0
+---
+
+# laranja docs
+
+**laranja** deploys your Node.js app to your own AWS account from your code — no
+YAML, no console clicking, no separate infrastructure project. You write an
+Express app plus a few functions or decorators; laranja reads the code, figures
+out the infrastructure, and ships it.
+
+```bash
+npm install -D @alzulejos/laranja
+npx laranja deploy
+```
+
+## Start here
+
+- **[Introduction](./getting-started/introduction.md)** — what laranja is and the ideas behind it.
+- **[Installation](./getting-started/installation.md)** — prerequisites and setup.
+- **[Quickstart](./getting-started/quickstart.md)** — from zero to a live URL.
+- **[How it works](./getting-started/how-it-works.md)** — how your code becomes a running app on AWS.
+
+## Guides
+
+- **[HTTP apps](./guides/http-apps.md)** — deploy your app behind a public URL with the `http()` marker.
+- **[Cron jobs](./guides/cron-jobs.md)** — scheduled functions with `@Cron` / `cron()`.
+- **[Queues](./guides/queues.md)** — SQS consumers with `@Queue` / `queue()`.
+- **[Schedules](./guides/schedules.md)** — the `rate()` / `every()` builders and raw expressions.
+- **[Environment variables](./guides/environment-variables.md)** — `env`, `STAGE`, and resolution.
+- **[Stages & environments](./guides/stages-and-environments.md)** — dev / staging / prod with one codebase.
+
+## Reference
+
+- **[CLI commands](./reference/commands.md)** — `init`, `logout`, `plan`, `deploy`, `destroy`, `logs`, `eject`.
+- **[Config file](./reference/config-file.md)** — every field in `laranja.config.ts`.
+- **[Decorators & markers](./reference/decorators-and-markers.md)** — `@Cron`, `@Queue`, `cron`, `queue`, `http`, `env`.
+- **[What gets deployed](./reference/what-gets-deployed.md)** — the AWS resources and how they're named.
+
+> **Status:** v1 targets **AWS** with **Express** today; **NestJS support is
+> coming**. The internal model is provider- and framework-neutral, so new clouds
+> and frameworks land without changing your app code.