@warlock.js/core 4.0.174 → 4.1.2

package/skills/use-localization/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: use-localization
+description: 'Multi-locale translations via `groupedTranslations` (declare keys), `t()` / `request.t()` / `request.trans()` (look up), `request.getLocaleCode()` (detect locale from headers/query), `getLocalized` (pick the right value from a localized-array column). Triggers: `groupedTranslations`, `t`, `request.t`, `request.trans`, `request.transFrom`, `request.getLocaleCode`, `request.setLocaleCode`, `getLocalized`; "add a translation key", "resolve a localized error message", "detect request locale", "pick the right per-locale column value"; typical import `import { t, getLocalized } from "@warlock.js/core"`. Skip: resource output — `@warlock.js/core/define-resource/SKILL.md`; module scaffold — `@warlock.js/core/create-module/SKILL.md`; competing libs `i18next`, `react-intl`, raw `@mongez/localization`.'
+---
+
+# Warlock — translate keys + pick localized values
+
+Two related but distinct jobs:
+
+1. **Translation keys** — string identifiers like `"products.notFound"` mapped to per-locale strings (`en`, `ar`, ...). Used for error messages, response copy, anything that needs to render differently per locale.
+2. **Localized columns** — a model column that stores `[{ localeCode: "en", value: "Hello" }, { localeCode: "ar", value: "مرحبا" }]`. Used for content that varies by locale (product names, article titles).
+
+Both pivot on **the request's locale** — auto-detected from headers / query string, defaulting to a config value.
+
+## The shape
+
+```ts
+// 1. Declare keys (auto-loaded from src/app/<module>/utils/locales.ts)
+import { groupedTranslations } from "@mongez/localization";
+
+groupedTranslations("products", {
+  notFound: { en: "Product not found", ar: "المنتج غير موجود" },
+  created:  { en: "Product created",  ar: "تم إنشاء المنتج" },
+});
+
+// 2. Look up in a controller / service
+import { t } from "@warlock.js/core";
+
+throw new ResourceNotFoundError(t("products.notFound"));
+// or via the request:
+return response.success({ message: request.t("products.created") });
+
+// 3. Pick a value from a localized-array column
+import { getLocalized } from "@warlock.js/core";
+
+const name = getLocalized(product.get("name_translations"));
+// → reads the current request's locale, returns the matching value
+```
+
+## Declaring translations — `groupedTranslations`
+
+Every module owns its translation namespace under `src/app/<module>/utils/locales.ts`. The file is auto-loaded at boot — you don't import it from anywhere; the framework picks it up via the module loader.
+
+```ts title="src/app/products/utils/locales.ts"
+import { groupedTranslations } from "@mongez/localization";
+
+groupedTranslations("products", {
+  notFound:    { en: "Product not found",      ar: "المنتج غير موجود" },
+  outOfStock:  { en: "Product out of stock",   ar: "المنتج غير متوفر" },
+  created:     { en: "Product created",         ar: "تم إنشاء المنتج" },
+  updated:     { en: "Product updated",         ar: "تم تحديث المنتج" },
+  deleted:     { en: "Product deleted",         ar: "تم حذف المنتج" },
+});
+```
+
+The first arg is the **group name** (matches the module's URL slug by convention). Lookup keys are dot-joined: `products.notFound`, `products.created`. Within a group, every key needs the same locale set — if you ship `en` for `notFound`, ship it for everything else too.
+
+You can also import `groupedTranslations` from `@warlock.js/core` (it's re-exported). Both imports work; the project's seed file uses `@mongez/localization` directly. Either is fine.
+
+### Placeholders
+
+```ts
+groupedTranslations("products", {
+  outOfStock: {
+    en: "Product :name is out of stock (current: :count)",
+    ar: "المنتج :name غير متوفر (الكمية: :count)",
+  },
+});
+
+// Lookup:
+t("products.outOfStock", { name: "Pen", count: 0 });
+// → "Product Pen is out of stock (current: 0)"
+```
+
+Placeholders use the `:name` syntax. The lookup helper substitutes them from the second argument.
+
+## Looking up translations — `t()`, `request.t()`, `request.trans()`
+
+Three calls, same job, slightly different reachability:
+
+```ts
+// 1. Top-level helper — works inside or outside a request.
+//    Inside a request: uses request's locale.
+//    Outside: uses the global default locale.
+import { t } from "@warlock.js/core";
+
+t("products.notFound");
+t("products.outOfStock", { name: "Pen", count: 0 });
+
+// 2. On the request object — explicit, scoped to that request.
+request.t("products.notFound");
+
+// 3. Alias for request.t — same behavior.
+request.trans("products.notFound");
+```
+
+All three lookups go through `@mongez/localization`'s `trans()` under the hood, with the locale pulled from the request context (or the global default).
+
+### Locale on a specific lookup
+
+```ts
+request.transFrom("ar", "products.notFound");
+// → "المنتج غير موجود" regardless of request's actual locale
+```
+
+Use when you want a value in a specific locale — e.g. sending a notification to a user whose preferred locale differs from the current request's.
+
+## Locale detection — `request.getLocaleCode()`
+
+The framework reads the locale from the incoming request in this order:
+
+1. **`translation-locale-code` header** (first priority).
+2. **`locale` header**.
+3. **`locale` query string param**.
+4. **Default** — `config.key("app.localeCode")` falling back to `"en"`.
+
+```ts
+const locale = request.getLocaleCode();
+// → "en" | "ar" | whatever the caller asked for
+```
+
+Configure the default:
+
+```ts title="src/config/app.ts"
+export default {
+  localeCode: "en",                       // app-wide default
+  // ...
+};
+```
+
+### Setting the locale programmatically
+
+```ts
+request.setLocaleCode("ar");
+```
+
+After this, every `request.t(...)` and `getLocalized(...)` in the same request returns Arabic. Useful for user-preference overrides (e.g. "this user has set their language to ar in their profile — switch the request's locale on auth").
+
+## Localized columns — `getLocalized`
+
+When a column stores per-locale values as an array:
+
+```ts
+// Schema (Seal):
+name_translations: v.array(
+  v.object({
+    localeCode: v.string(),  // "en", "ar", ...
+    value: v.string(),
+  })
+),
+
+// Stored row (DB):
+{
+  name_translations: [
+    { localeCode: "en", value: "Hello World" },
+    { localeCode: "ar", value: "مرحبا" },
+  ],
+}
+```
+
+Pick the right one for the current request:
+
+```ts
+import { getLocalized } from "@warlock.js/core";
+
+const name = getLocalized(product.get("name_translations"));
+// → "Hello World" if request locale is "en"
+// → "مرحبا" if request locale is "ar"
+```
+
+### Signature
+
+```ts
+getLocalized(
+  values: LocalizedObject[],
+  localeCode?: string,
+  key = "value",
+): unknown;
+```
+
+- **`values`** — the localized-array column.
+- **`localeCode`** *(optional)* — pin to a specific locale. Defaults to the current request's locale (reads via `useRequestStore()`).
+- **`key`** *(default `"value"`)* — which property of the matched entry to return. Use a different key if your localized objects store the value under a different name.
+
+```ts
+const slug = getLocalized(product.get("slug_translations"), undefined, "value");
+const tagline = getLocalized(product.get("name_translations"), "fr");  // force French
+```
+
+### Use inside a resource for clean per-locale responses
+
+```ts title="src/app/products/resources/product.resource.ts"
+import { defineResource, getLocalized } from "@warlock.js/core";
+
+export const ProductResource = defineResource({
+  schema: {
+    id: "string",
+    name: function (_value, resource) {
+      return getLocalized(resource.get("name_translations"));
+    },
+    description: function (_value, resource) {
+      return getLocalized(resource.get("description_translations"));
+    },
+  },
+});
+```
+
+The `localized` cast (`name: "localized"`) handles the common case directly — reach for a `getLocalized` resolver only when the stored key differs from the output key or you need a fallback.
+
+The wire response always returns the right locale string — no caller-side branching needed.
+
+## Patterns
+
+### Translated error in a service
+
+```ts title="src/app/products/services/get-product.service.ts"
+import { ResourceNotFoundError, t } from "@warlock.js/core";
+import { productsRepository } from "../repositories/products.repository";
+
+export async function getProductService(id: string) {
+  const product = await productsRepository.find(id);
+  if (!product) throw new ResourceNotFoundError(t("products.notFound"));
+  return product;
+}
+```
+
+The error's message is locale-aware — the `inject-request-context` middleware catches the error and the response carries the translated string.
+
+### Translated response message in a controller
+
+```ts
+export const createProductController: GuardedRequestHandler<CreateProductSchema> = async (
+  request,
+  response,
+) => {
+  const product = await createProductService(request.validated());
+  return response.success({
+    message: request.t("products.created"),
+    product,
+  });
+};
+```
+
+### Per-locale product names with a localized column
+
+```ts
+import { v } from "@warlock.js/seal";
+
+export const productSchema = v.object({
+  // ...
+  name_translations: v.array(
+    v.object({
+      localeCode: v.string(),
+      value: v.string(),
+    }),
+  ),
+  // ...
+});
+
+// Create:
+await Product.create({
+  name_translations: [
+    { localeCode: "en", value: "Pen" },
+    { localeCode: "ar", value: "قلم" },
+  ],
+});
+
+// Read (via a resource that uses getLocalized):
+// → response includes "name": "Pen" for en, "قلم" for ar
+```
+
+### Caller overrides locale via query string
+
+```bash
+GET /products/42?locale=ar
+```
+
+`request.getLocaleCode()` returns `"ar"` — every `request.t(...)` and resource-output `getLocalized` returns Arabic. No app code changes required.
+
+## Gotchas
+
+- **Locales files are auto-loaded — don't import them.** `src/app/<module>/utils/locales.ts` is picked up by the module loader on boot. Importing it manually causes double-registration warnings.
+- **Group names should match module URL slugs.** `groupedTranslations("products", ...)` for the `/products` module. Mismatch breaks the convention but doesn't throw.
+- **Every key needs every locale.** If a key is missing for the active locale, the lookup falls back to the key string itself (`"products.notFound"` literally appears in the response). Always ship all locales together when adding a key.
+- **`t()` outside a request uses the global default.** `Application.environment === "test"` or background jobs without a request context get the configured `app.localeCode`, not whatever the most recent request used.
+- **`getLocalized` returns `undefined` if no entry matches.** Empty `name_translations` arrays, missing-locale arrays, or `undefined` columns all surface as `undefined`. Check at the read site or set a default in the resource: `getLocalized(values) ?? "n/a"`.
+- **`request.getLocaleCode()` populates `_locale` on first read.** The second call returns the cached value. Calling `setLocaleCode` after the first read overrides cleanly.
+- **The `t()` helper is exported from `@warlock.js/core`.** Don't import `trans` from `@mongez/localization` directly inside controllers/services — `t()` adds request-context awareness on top.
+- **Placeholders are case-sensitive.** `:name` does NOT match `:Name`. The translation string must spell the placeholder exactly as you pass it.
+
+## See also
+
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — error helpers that pair with translated messages (`response.notFound({ error: t("...") })`).
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — using `getLocalized` inside resource output for clean per-locale responses.
+- [`create-module/SKILL.md`](../create-module/SKILL.md) — the `utils/locales.ts` file is part of the generated module scaffold.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — `utils/locales.ts` is auto-loaded; the suffix is mandatory.

package/skills/use-middleware/SKILL.md

@@ -0,0 +1,221 @@
+---
+name: use-middleware
+description: 'Attach built-in HTTP middleware to routes via the `middleware` namespace from `@warlock.js/core` — rateLimit, concurrencyLimit, maxBodySize, idempotency, maintenance, ipFilter, cache. Plus `X-Request-Id` correlation, wired automatically. Triggers: `middleware.rateLimit`, `middleware.concurrencyLimit`, `middleware.maxBodySize`, `middleware.idempotency`, `middleware.maintenance`, `middleware.ipFilter`, `middleware.cache`, `X-Request-Id`, `Idempotency-Key`; "add rate limiting", "dedupe writes by idempotency key", "cap concurrent requests", "block IPs", "cache a GET response"; typical import `import { middleware } from "@warlock.js/core"`. Skip: author custom middleware — `@warlock.js/core/write-middleware/SKILL.md`; cache singleton — `@warlock.js/cache/cache-basics/SKILL.md`; competing libs `@fastify/rate-limit` direct, `express-rate-limit`, `helmet`.'
+---
+
+# Warlock — use built-in middleware
+
+`@warlock.js/core` ships seven HTTP middlewares behind a single namespace object: `middleware`. They cover the patterns most apps reach for — rate limit, concurrency cap, body size cap, idempotency, maintenance mode, IP filter, response cache. Plus the request-id echo, which isn't a middleware but lives in the same mental category.
+
+```ts
+import { middleware } from "@warlock.js/core";
+
+middleware.rateLimit({ max: 5, duration: 60_000 });
+middleware.idempotency();
+middleware.maxBodySize("2mb");
+// ... etc
+```
+
+For authoring your OWN middleware (custom guards, enrichment, etc.), see [`write-middleware`](../write-middleware/SKILL.md).
+
+## The catalog
+
+All seven are factories — call them to get a `Middleware`. All set `errorCode` on the response so clients can branch without parsing error text (see `HttpErrorCodes` from `@warlock.js/core`). Error messages are translation-driven — keys live under the `http` group in `src/app/shared/utils/locales.ts`.
+
+| Factory | What it does | Status on reject |
+|---|---|---|
+| `middleware.rateLimit({ max, duration })` | Per-route/group cap on top of global `@fastify/rate-limit` | 429 + `Retry-After` |
+| `middleware.concurrencyLimit(n)` | Cap in-flight requests; no queue, fast reject | 429 + `Retry-After: 1` |
+| `middleware.maxBodySize("2mb")` | Per-route `Content-Length` cap | 413 |
+| `middleware.idempotency()` | Dedupe writes by `Idempotency-Key` header; cached replay | 422 on conflict |
+| `middleware.maintenance()` | Globally toggle 503 with allowlist bypass | 503 + `Retry-After` |
+| `middleware.ipFilter({ allow, deny })` | Allowlist/denylist by client IP | 403 (fail-closed) |
+| `middleware.cache(opts)` | Cache + replay successful JSON responses | n/a |
+
+Each is documented inline (JSDoc + `@example`) — read the file under `@warlock.js/core/src/http/middleware/<name>.middleware.ts` for the full option surface.
+
+## `rateLimit` vs `concurrencyLimit`
+
+- **Rate limit** caps **requests per time window** — 5 logins/minute per IP. Use for abuse prevention, cost-control on cheap-but-spammable endpoints.
+- **Concurrency limit** caps **in-flight requests at any instant** — 3 simultaneous report generations. Use for expensive endpoints where parallel calls would overload the worker (CPU-bound, large memory, slow third-party).
+
+Both counters are **process-local**. With N replicas the effective cap is N × value. For globally-shared rate limits, configure `@fastify/rate-limit` with a Redis store via `http.rateLimit` instead.
+
+```ts
+import { middleware } from "@warlock.js/core";
+
+router.post("/ai/summarize", summarizeController, {
+  middleware: [
+    middleware.rateLimit({ max: 60, duration: 60 * 60 * 1000 }), // 60/hr per user
+    middleware.concurrencyLimit(5),                              // ≤5 in-flight at once
+  ],
+});
+```
+
+## `idempotency` — must run after auth
+
+The cache key is `idem:{userType}:{userId|ip}:{key}` so user A can't replay user B's key. That requires `request.user` to be populated, so order it **after** `authMiddleware`:
+
+```ts
+import { authMiddleware } from "@warlock.js/auth";
+import { middleware } from "@warlock.js/core";
+
+router.post("/orders", createOrderController, {
+  middleware: [authMiddleware("client"), middleware.idempotency()],
+});
+```
+
+Lifecycle:
+
+1. **Method not eligible** (GET / HEAD) → pass through.
+2. **No `Idempotency-Key` header** → pass through (the primitive is opt-in by the client).
+3. **Key + same body within TTL** (default 24h) → replays the cached response with `Idempotent-Replay: true`. Handler does NOT re-run.
+4. **Key + different body** → 422 `IdempotencyKeyConflict`. Client bug — same key must mean same intent.
+5. **Cache miss** → runs handler; on response sent, caches `{ status, body, bodyHash }` for TTL.
+
+Server errors (5xx) are not cached — clients can retry past a 5xx. 4xx responses ARE cached (they're deterministic outcomes of the request).
+
+**Client side, this only works if the client reuses the same key across retries.** Generate once at "intent to submit" time, persist it across the retry loop, drop it on confirmed success or final failure.
+
+## `maxBodySize` vs the global `http.bodyLimit`
+
+`http.bodyLimit` in config is read by Fastify at server-start and applies to every body. `middleware.maxBodySize()` is a per-route middleware on top — it checks `Content-Length` after route match and rejects with 413 before body parsing runs. Use both: global as a safety net, per-route for tight caps on small-payload endpoints.
+
+```ts
+// src/config/http.ts
+export default { bodyLimit: 10 * 1024 * 1024 }; // 10MB globally
+
+// src/app/comments/routes.ts
+import { middleware } from "@warlock.js/core";
+
+router.post("/comments", createCommentController, {
+  middleware: [middleware.maxBodySize("8kb")], // comments shouldn't be larger
+});
+```
+
+## `maintenance` is config-driven
+
+Toggle via `http.maintenance.enabled` (and `http.maintenance.allowlist`, default `["/health"]`). Flipping the flag requires a process restart — there's no runtime hot-flip yet. Register at the app-level so every route is covered:
+
+```ts
+// src/config/http.ts
+import { middleware } from "@warlock.js/core";
+
+export default {
+  maintenance: { enabled: env("MAINTENANCE_MODE") === "true" },
+  middleware: {
+    all: [middleware.maintenance({ allowlist: ["/health", "/admin/*"] })],
+  },
+};
+```
+
+## `ipFilter` — fail-closed
+
+`deny` wins over `allow`. If the IP can't be read (empty / unparseable), the request is rejected with 403. Reads via `request.detectIp()` which honors `X-Real-IP` and `X-Forwarded-For` (Fastify starts with `trustProxy: true`).
+
+```ts
+import { middleware } from "@warlock.js/core";
+
+// Group-wide: pass it through the group's `middleware` array (there is no
+// `router.use()` — middleware attaches via group options or route options).
+router.group(
+  {
+    prefix: "/admin",
+    middleware: [middleware.ipFilter({ allow: ["10.0.0.0/8", "203.0.113.42"] })],
+  },
+  () => {
+    router.get("/dashboard", dashboardController);
+  },
+);
+
+// Per-route: pass it in the route's `middleware` array.
+router.post("/webhooks/provider", webhookController, {
+  middleware: [middleware.ipFilter({ allow: ["198.51.100.0/24"] })],
+});
+```
+
+IPv4 CIDR matching only — IPv6 patterns are matched as exact strings.
+
+## `cache` — response caching
+
+Cache successful JSON responses by key, serve replays from cache until TTL expiry. Useful for expensive read endpoints (analytics dashboards, expensive aggregations).
+
+```ts
+import { middleware } from "@warlock.js/core";
+
+router.get("/analytics/summary", summaryController, {
+  middleware: [middleware.cache({ cacheKey: "analytics.summary", ttl: 300 })],
+});
+```
+
+`cacheKey` can be a string OR a function `(request) => string | Promise<string>` for per-request keys. Excludes failures and omits `["user", "settings"]` from the cached body by default.
+
+## Composed example
+
+Tight cap on logins, concurrency + idempotency on AI calls:
+
+```ts
+import { authMiddleware } from "@warlock.js/auth";
+import { middleware, router } from "@warlock.js/core";
+
+router.post("/auth/login", loginController, {
+  middleware: [
+    middleware.rateLimit({ max: 5, duration: 60_000 }),
+    middleware.maxBodySize("4kb"),
+  ],
+});
+
+router.group({ middleware: [authMiddleware("client")] }, () => {
+  router.post("/ai/summarize", summarizeController, {
+    middleware: [
+      middleware.rateLimit({ max: 60, duration: 60 * 60 * 1000 }),
+      middleware.concurrencyLimit(5),
+      middleware.idempotency({ ttl: 60 * 60 }),
+    ],
+  });
+});
+```
+
+## Request ID correlation
+
+Not a middleware — wired into `Request.setRequest()` and `createRequestStore()`. Nothing to register; it runs on every request automatically.
+
+Every request gets a `request.id` (32-char random string by default). The framework:
+
+1. **Inherits** an incoming `X-Request-Id` header if it's well-formed (printable ASCII, ≤128 chars) — so proxies / FE / edge can propagate their own correlation ID end-to-end.
+2. **Echoes** `X-Request-Id: <request.id>` on every response — clients can show "request 7a3f… failed" in error toasts; support can grep logs by that single string.
+3. **Stamps** `request.id` into every `request.log()` / `response.log()` line — so the per-request correlation is already in your log channel.
+
+Configure via `http.requestId`:
+
+```ts
+// src/config/http.ts
+import { ulid } from "ulid"; // if you prefer ULID over the default random string
+
+export default {
+  requestId: {
+    header: "X-Request-Id",   // outbound + inbound header name
+    generator: () => ulid(),  // optional override
+    enabled: true,            // set false to disable both inherit + echo
+  },
+};
+```
+
+**Request ID is correlation, not idempotency.** A fresh ID is generated on every retry; same key, different ID. For write deduplication on retry, use `middleware.idempotency()`.
+
+## Gotchas
+
+- **Bare factory names are not exported.** Always reach for them via `middleware` (`middleware.rateLimit`, not `rateLimitMiddleware`). The internal `*Middleware`-suffixed names are an in-package code-organization detail.
+- **Idempotency must run after auth.** The cache key includes `request.user` for scope-isolation. Putting it before auth silently falls back to IP-scope for every request.
+- **In-process counters lose state on restart.** `middleware.rateLimit` and `middleware.concurrencyLimit` use module-scoped `Map`s. A redeploy resets every window/counter. For globally-shared limits, use `@fastify/rate-limit` with a Redis store.
+- **Idempotency clients must reuse the key across retries.** If your client generates a new UUID on every attempt, idempotency is a no-op. Generate once at "intent" time.
+- **`ipFilter` fail-closed.** Empty / unparseable IP = denied. Internal callers (Unix sockets, local processes) need explicit allowlisting.
+- **Maintenance flag is config-driven, restart required.** No runtime hot-flip. Flip via env-var + redeploy.
+- **Error messages come from translations.** All status-text messages are `t("http.X")` lookups. The project's `locales.ts` template ships the `http` group. If you fork the template and remove it, errors will fall back to the key name.
+
+## See also
+
+- [`write-middleware/SKILL.md`](../write-middleware/SKILL.md) — author your OWN middleware (custom guards, enrichment).
+- [`register-route/SKILL.md`](../register-route/SKILL.md) — where middleware attaches: `router.group` and route-options.
+- [`send-response/SKILL.md`](../send-response/SKILL.md) — the response helpers used to short-circuit (`tooManyRequests`, `contentTooLarge`, `serviceUnavailable`, etc.).
+- [`@warlock.js/cache/cache-basics/SKILL.md`](../../../cache/skills/cache-basics/SKILL.md) — the cache singleton (`@warlock.js/cache`) that backs `middleware.idempotency` and `middleware.cache`.