@warlock.js/core 4.0.174 → 4.1.3

package/skills/benchmark-code/SKILL.md

@@ -0,0 +1,256 @@
+---
+name: benchmark-code
+description: 'Wrap a function with `measure(name, fn, options?)` to time it and classify the latency — onComplete/onError/onFinish hooks, `latencyRange` thresholds, `BenchmarkProfiler` for percentiles, `BenchmarkSnapshots` for raw captures. Triggers: `measure`, `BenchmarkProfiler`, `BenchmarkSnapshots`, `BenchmarkChannel`, `ConsoleChannel`, `latencyRange`, `shouldBenchmarkError`; "time this operation", "profile a slow service", "emit p50/p95/p99 metrics", "classify latency against thresholds"; typical import `import { measure, BenchmarkProfiler } from "@warlock.js/core"`. Skip: retry composition — `@warlock.js/core/retry-operation/SKILL.md`; benchmark config wiring — `@warlock.js/core/configure-app/SKILL.md`; competing libs `prom-client`, `pino`, `perf_hooks`, `console.time`.'
+---
+
+# Warlock — benchmark code
+
+`measure()` is the workhorse. It wraps any sync-or-async function, captures its latency, classifies it against an excellent/poor band, calls your hooks, and returns a tagged result. Around it, two optional accumulators: `BenchmarkProfiler` (percentiles across many calls) and `BenchmarkSnapshots` (raw error captures for post-mortem).
+
+## The shape
+
+```ts
+import { measure } from "@warlock.js/core";
+
+const result = await measure("db.findUser", () => db.users.findOne({ id }));
+
+if (result.success) {
+  console.log(result.value);          // T
+  console.log(result.latency);        // ms
+  console.log(result.state);          // "excellent" | "good" | "poor"
+} else {
+  console.error(result.error);
+}
+```
+
+`measure()` always *returns* — it never re-throws. The return type is `BenchmarkSuccessResult<T> | BenchmarkErrorResult`, discriminated by `result.success`. The one exception: `shouldBenchmarkError` returning false re-throws (see below).
+
+## `BenchmarkResult` — what you get back
+
+Both success and error results share:
+
+```ts
+{
+  name: string;                              // your measurement name
+  latency: number;                           // ms (rounded)
+  state: "excellent" | "good" | "poor";      // see latencyRange
+  tags?: Record<string, string>;             // whatever you passed in options.tags
+  startedAt: Date;
+  endedAt: Date;
+}
+```
+
+Plus, discriminated by `success`:
+
+```ts
+// success
+{ success: true,  value: T }
+
+// error
+{ success: false, error: unknown }
+```
+
+## `latencyRange` — classifying speed
+
+Pass thresholds to get a `state` you can route on:
+
+```ts
+await measure("db.findUser", () => db.users.findOne({ id }), {
+  latencyRange: { excellent: 100, poor: 500 },
+});
+
+// latency <= 100ms  → state: "excellent"
+// 100ms < lat < 500 → state: "good"
+// latency >= 500ms  → state: "poor"
+```
+
+Without `latencyRange`, every successful result is `"good"` and every error is `"poor"`. Set it globally in `src/config/benchmark.ts` (see `BenchmarkConfigurations`) and `measure()` will fall back to that — no need to repeat it per call.
+
+## Hooks
+
+Three optional callbacks, called in order — `onComplete`/`onError` first (one of them, never both), then `onFinish` (always):
+
+```ts
+await measure("send-email", () => mailer.send(payload), {
+  latencyRange: { excellent: 200, poor: 2000 },
+  onComplete: (result) => metrics.record(result.latency),
+  onError: (result) => logger.error("email failed", result.error),
+  onFinish: (result) => logger.info(`${result.name} → ${result.state}`),
+});
+```
+
+`tags` rides along on the result and is yours to use however:
+
+```ts
+await measure("http.outbound", () => fetch(url), {
+  tags: { service: "stripe", endpoint: "/charges" },
+});
+```
+
+## Selective error capture — `shouldBenchmarkError`
+
+Business errors (4xx, validation) are not infrastructure problems and shouldn't pollute your latency stats. Return `false` to *re-throw* the error without producing a benchmark result:
+
+```ts
+await measure("create-user", () => createUser(input), {
+  shouldBenchmarkError: (err) => !(err instanceof ValidationError),
+});
+```
+
+Default is `true` — every thrown error becomes a `BenchmarkErrorResult`.
+
+## `enabled: false` — pass-through
+
+Wrapping costs almost nothing (one `performance.now()`, one closure), but if you want a literal no-op for a hot path:
+
+```ts
+const result = await measure("hot-path", () => work(), { enabled: false });
+// result.latency === 0
+// result.state   === "excellent"
+// no hooks fire
+```
+
+`fn()` still runs and its return value still lands in `result.value`. The wrapper just skips timing and hooks.
+
+## `BenchmarkProfiler` — rolling percentiles
+
+For high-volume operations where you want p50/p95/p99 rather than per-call hooks:
+
+```ts
+import { BenchmarkProfiler, ConsoleChannel, measure } from "@warlock.js/core";
+
+const profiler = new BenchmarkProfiler({
+  maxSamples: 1000,                  // ring buffer per operation name
+  channels: [new ConsoleChannel()],  // where stats go on flush()
+  flushEvery: 60_000,                // auto-flush every minute
+});
+
+for (let i = 0; i < 5; i++) {
+  await measure(
+    "db.findUser",
+    () => db.users.findOne({ id: i }),
+    { profiler, latencyRange: { excellent: 50, poor: 300 } },
+  );
+}
+
+const stats = profiler.stats("db.findUser");
+// { p50, p90, p95, p99, avg, min, max, count, errors, errorRate, firstSeenAt, lastSeenAt }
+```
+
+`profiler.flush()` (manual or auto) hands `allStats()` to every registered `BenchmarkChannel`. The built-in `ConsoleChannel` prints a `console.table` per operation. `NoopChannel` is the default — useful when you want stats accessible via `profiler.stats(name)` without external emission.
+
+Wire a profiler globally through `BenchmarkConfigurations.profiler` in `src/config/benchmark.ts` so every `measure()` call records by default.
+
+### Custom channel
+
+```ts
+import type { BenchmarkChannel, BenchmarkStats } from "@warlock.js/core";
+
+export class DatadogChannel implements BenchmarkChannel {
+  public async onFlush(stats: Record<string, BenchmarkStats>): Promise<void> {
+    for (const [name, operationStats] of Object.entries(stats)) {
+      await datadog.gauge(`latency.${name}.p95`, operationStats.p95);
+    }
+  }
+}
+```
+
+Pass it via `channels: [new DatadogChannel()]`.
+
+## `BenchmarkSnapshots` — raw captures
+
+When percentiles aren't enough — you need the actual failing inputs/errors for a post-mortem:
+
+```ts
+import { BenchmarkSnapshots, measure } from "@warlock.js/core";
+
+const snapshots = new BenchmarkSnapshots({
+  maxSnapshots: 100,
+  capture: "error",        // "error" (default, safe) | "value" | "all"
+});
+
+await measure("payment.charge", () => stripe.charge(payload), { snapshotContainer: snapshots });
+
+const failed = snapshots.getSnapshots("payment.charge");
+// array of full BenchmarkErrorResult — error, latency, startedAt, tags
+```
+
+`capture: "value"` and `"all"` store the success return value in memory — fine for low-volume diagnostics, dangerous in production. The "error" default keeps memory bounded by the failure rate.
+
+## Globals via `src/config/benchmark.ts`
+
+```ts title="src/config/benchmark.ts"
+import {
+  BenchmarkProfiler,
+  ConsoleChannel,
+  type BenchmarkConfigurations,
+} from "@warlock.js/core";
+
+const benchmarkConfig: BenchmarkConfigurations = {
+  enabled: true,
+  latencyRange: { excellent: 100, poor: 500 },
+  profiler: new BenchmarkProfiler({
+    maxSamples: 1000,
+    channels: [new ConsoleChannel()],
+    flushEvery: 60_000,
+  }),
+};
+
+export default benchmarkConfig;
+```
+
+Every `measure()` call without an explicit `latencyRange`/`profiler` falls back to these. Per-call options always win.
+
+## Common patterns
+
+### Measure a service call
+
+```ts
+const result = await measure("create-order", () => createOrderService(input));
+
+if (!result.success) {
+  return response.badRequest({ error: t("order.failed") });
+}
+
+return response.successCreate({ order: result.value });
+```
+
+### Measure an external HTTP request
+
+```ts
+const result = await measure(
+  "stripe.charge",
+  () => stripe.charges.create({ amount, currency, source }),
+  {
+    latencyRange: { excellent: 200, poor: 3000 },
+    tags: { gateway: "stripe" },
+    shouldBenchmarkError: (err) => err instanceof NetworkError,
+  },
+);
+```
+
+### Compose with `retry()`
+
+```ts
+import { measure } from "@warlock.js/core";
+import { retry } from "@mongez/reinforcements";
+
+await measure("publish-event", () =>
+  retry(() => bus.publish(event), { attempts: 4, delay: 200 }),
+);
+```
+
+The `latency` is the *total* time including retries — useful for the SLO you actually care about. (`retry` moved to `@mongez/reinforcements`; `count` is now `attempts` — total tries.)
+
+## Gotchas
+
+- **Name collisions aggregate.** Two calls to `measure("foo", …)` share one profiler bucket. Make `name` specific (`db.findUser`, not `db.query`) so percentiles mean something.
+- **`measure()` doesn't propagate AbortSignal.** If `fn` is cancellable, plumb that through yourself — the wrapper only times.
+- **Don't `measure()` synchronous trivia.** A `Math.round` call isn't worth a microsecond of overhead. Reserve for things that *can* be slow.
+- **Snapshots with `"value"` retain references.** If `value` holds a request stream or a large buffer, you've kept it in memory until eviction.
+- **`shouldBenchmarkError` re-throws.** Make sure the caller is ready for that, or set it conservatively (`true` by default).
+
+## See also
+
+- [`retry-operation/SKILL.md`](../retry-operation/SKILL.md) — wrapping flaky operations with retry; composes inside `measure()`.
+- [`configure-app/SKILL.md`](../configure-app/SKILL.md) — wiring `src/config/benchmark.ts`.

package/skills/build-restful/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: build-restful
+description: 'Generate standard CRUD endpoints — via `router.route(path).list().show().create().update().destroy()` chain or the `Restful` base class. Pick the chain by default; reach for `Restful` when you want repository-bound defaults. Triggers: `router.route`, `Restful`, `router.restfulResource`, `RouteResource`, `.crud`, `.nest`, `beforeCreate`, `onCreate`; "build a CRUD API", "register list/show/create/update/destroy", "repository-bound default handlers", "override a single REST action"; typical import `import { router, Restful } from "@warlock.js/core"`. Skip: wider router surface — `@warlock.js/core/register-route/SKILL.md`; per-action controllers — `@warlock.js/core/create-controller/SKILL.md`; wire mapping — `@warlock.js/core/define-resource/SKILL.md`; competing pattern: hand-rolled controllers, `@nestjs/swagger` decorator-driven CRUD.'
+---
+
+# Warlock — build a RESTful resource
+
+Standard CRUD comes in two flavors. The **router chain** is thin: you write one controller per action and chain them via `router.route(path)`. The **`Restful` base class** is thick: it wires a repository to default handlers — list/get/create/update/patch/delete plus bulkDelete — and you override hooks only where you need to.
+
+## The shape
+
+```ts title="src/app/<module>/routes.ts"
+import { router } from "@warlock.js/core";
+import { guarded } from "app/shared/utils/router";
+import { createFaqController } from "./controllers/create-faq.controller";
+import { deleteFaqController } from "./controllers/delete-faq.controller";
+import { getFaqController } from "./controllers/get-faq.controller";
+import { listFaqsController } from "./controllers/list-faqs.controller";
+import { updateFaqController } from "./controllers/update-faq.controller";
+
+guarded(() => {
+  router
+    .route("/faqs")
+    .list(listFaqsController)
+    .show(getFaqController)
+    .create(createFaqController)
+    .update(updateFaqController)
+    .destroy(deleteFaqController);
+});
+```
+
+This is the project default. Five controllers, one chain, auto-loaded.
+
+## The chain — `router.route(path)`
+
+`router.route(path)` returns a `RouteBuilder`. Each named slot maps to a verb + path:
+
+| Method                                | Verb     | Path        |
+| ------------------------------------- | -------- | ----------- |
+| `.list(handler)`                      | `GET`    | `/path`     |
+| `.show(handler)`                      | `GET`    | `/path/:id` |
+| `.create(handler)`                    | `POST`   | `/path`     |
+| `.update(handler)`                    | `PUT`    | `/path/:id` |
+| `.patch(handler)`                     | `PATCH`  | `/path/:id` |
+| `.destroy(handler)`                   | `DELETE` | `/path/:id` |
+| `.get(handler)`                       | `GET`    | `/path`     |
+| `.post(handler)`                      | `POST`   | `/path`     |
+| `.put(handler)`                       | `PUT`    | `/path`     |
+| `.delete(handler)`                    | `DELETE` | `/path`     |
+| `.getOne` / `.postOne` / `.deleteOne` | verb     | `/path/:id` |
+
+The semantic aliases (`list`, `show`, `create`, `update`, `destroy`, `patch`) are just thin wrappers — same registration. Methods you don't call don't register. Each method returns the builder, so you chain.
+
+### `.crud({...})`
+
+Sugar for setting up all six slots in one call:
+
+```ts
+router.route("/products").crud({
+  list: listProductsController,
+  show: getProductController,
+  create: createProductController,
+  update: updateProductController,
+  destroy: removeProductController,
+  patch: patchProductController,
+});
+```
+
+### `.nest(path)`
+
+For nested resources like `/posts/:id/comments`:
+
+```ts
+router
+  .route("/posts/:id")
+  .show(showPostController)
+  .nest("/comments")
+  .list(listCommentsController)
+  .create(createCommentController);
+```
+
+## The `Restful` base class
+
+When you want default CRUD handlers wired straight to a repository, extend `Restful<T>`:
+
+```ts
+import { Restful, type RouteResource, v } from "@warlock.js/core";
+import { UsersRepository } from "./repositories/users.repository";
+import type { User } from "./models/user/user.model";
+
+export class UsersRestful extends Restful<User> implements RouteResource {
+  protected repository = new UsersRepository();
+
+  protected recordName = "user";
+  protected recordsListName = "users";
+
+  public cache = true;
+
+  protected returnOn = {
+    create: "record",
+    update: "record",
+    delete: "record",
+    patch: "record",
+  };
+
+  public validation = {
+    create: {
+      schema: v.object({
+        name: v.string().required().min(2),
+        email: v.email().required(),
+      }),
+    },
+    update: {
+      schema: v.object({
+        name: v.string().min(2),
+      }),
+    },
+  };
+}
+
+// `validation` is consumed via duck-typing by `router.restfulResource()`.
+// The base `Restful` class doesn't formally declare it — you add it on the
+// subclass and the router picks it up at registration time.
+```
+
+Wire it to the router via `router.restfulResource(path, instance, options?)`:
+
+```ts
+import { router } from "@warlock.js/core";
+
+router.restfulResource("/users", new UsersRestful());
+```
+
+This registers:
+
+| Path        | Verb     | Method        |
+| ----------- | -------- | ------------- |
+| `/users`    | `GET`    | `list()`      |
+| `/users/:id`| `GET`    | `get()`       |
+| `/users`    | `POST`   | `create()`    |
+| `/users/:id`| `PUT`    | `update()`    |
+| `/users/:id`| `PATCH`  | `patch()`     |
+| `/users/:id`| `DELETE` | `delete()`    |
+| `/users`    | `DELETE` | `bulkDelete()`|
+
+`bulkDelete` expects an array of ids in the `id` field; it 400s otherwise. All actions except `bulkDelete` only register when the corresponding method is defined on the class — `Restful` provides them all by default.
+
+### Filtering registered actions
+
+```ts
+router.restfulResource("/users", new UsersRestful(), {
+  only: ["list", "get"],
+});
+
+router.restfulResource("/users", new UsersRestful(), {
+  except: ["delete"],
+});
+
+router.restfulResource("/users", new UsersRestful(), {
+  replace: {
+    create: customCreateHandler,
+  },
+});
+```
+
+`replace` overrides a single action without rebuilding the class. `only` and `except` filter the action set.
+
+### Configurable bits on `Restful`
+
+- `recordName` / `recordsListName` — response keys for `{ [recordName]: model }` and `{ [recordsListName]: [...] }`. Default `"record"` and `"records"`.
+- `returnOn` — after create/update/delete/patch, return the single record (default) or the full list (`"records"`).
+- `cache` — when `true` (default), `list()` and `get()` use the repository's cached variants (`listCached`/`getCached`).
+- `validation` — per-action schemas read by `router.restfulResource()`. Add `validation = { create?, update?, patch? }` as a public field on your subclass; the router consumes whichever entries exist. The field isn't declared on the base `Restful` class — it's duck-typed off the resource at registration time (see `router.ts > manageValidation`).
+
+### Lifecycle hooks
+
+Override any of these `protected async` methods:
+
+| Hook                            | When                                      |
+| ------------------------------- | ----------------------------------------- |
+| `beforeCreate(request, response, model)` | New model instance, before `create`       |
+| `onCreate(request, response, record)`    | After successful `create`                 |
+| `beforeUpdate(request, response, record, old?)` | Before `update`                    |
+| `onUpdate(request, response, record, old)`      | After successful `update`           |
+| `beforePatch(request, response, record, old?)`  | Before `patch`                      |
+| `onPatch(request, response, record, old)`       | After successful `patch`            |
+| `beforeDelete(request, response, record)`       | Before `delete` (single + bulk)     |
+| `onDelete(request, response, record)`           | After successful `delete`           |
+| `beforeSave(request, response, record?, old?)`  | Before create/update/patch — shared |
+| `onSave(request, response, record, old?)`       | After create/update/patch — shared  |
+
+Returning a response from a `before*` hook short-circuits the action. Use for permission checks or computed-field assignment.
+
+## When to use which
+
+- **Default to the chain (`router.route(...)`)** with explicit per-action controllers — every module in the project uses this. Controllers stay thin, services own the logic, validation lives on the controller, and you can read `routes.ts` in five seconds.
+- **Reach for `Restful`** when the entity is genuinely vanilla CRUD against a repository with no per-action service variation. The hook ladder is more ceremony than five controllers if the actions diverge at all.
+- **Drop to hand-rolled controllers** when even one action breaks the CRUD shape — custom response wrappers, multi-step pipelines, non-`:id` lookups. Mixing is fine: chain the standard four, register the oddball as a separate `router.post(...)`.
+
+## Common patterns
+
+### Project default — five controllers behind a chain
+
+```ts
+import { router } from "@warlock.js/core";
+import { guarded } from "app/shared/utils/router";
+import { createProductController } from "./controllers/create-product.controller";
+import { getProductController } from "./controllers/get-product.controller";
+import { listProductsController } from "./controllers/list-products.controller";
+import { removeProductController } from "./controllers/remove-product.controller";
+import { updateProductController } from "./controllers/update-product.controller";
+
+guarded(() => {
+  router
+    .route("/products")
+    .list(listProductsController)
+    .show(getProductController)
+    .create(createProductController)
+    .update(updateProductController)
+    .destroy(removeProductController);
+});
+```
+
+### Public list + guarded mutations
+
+```ts
+router.prefix("/products", () => {
+  router.get("/", listProductsController);
+
+  guarded(() => {
+    router.post("/", createProductController);
+    router.patch("/:id", updateProductController);
+    router.delete("/:id", removeProductController);
+  });
+});
+```
+
+### Restful with override
+
+```ts
+class OrdersRestful extends Restful<Order> {
+  protected repository = new OrdersRepository();
+  protected recordName = "order";
+
+  protected async beforeCreate(request, response, order) {
+    order.set("organization_id", request.user.organizationId);
+    order.set("created_by", request.user.id);
+  }
+}
+
+router.restfulResource("/orders", new OrdersRestful());
+```
+
+## Gotchas
+
+- **`router.restfulResource` wraps `prefix(path, ...)` internally** — register inside `guarded(...)` to guard the whole set, or pass middleware via the options. Avoid registering the same prefix twice.
+- **`Restful.update` is `PUT`, `Restful.patch` is `PATCH`.** They differ — `update` uses `request.allExceptParams()`, `patch` uses `request.heavyExceptParams()`. Don't conflate them.
+- **`cache = true` reuses repository cache.** If the repository isn't cacheable, the cached methods silently fall through to the live query — set `cache = false` explicitly if you want to make that visible.
+- **`bulkDelete` reads `id` as an array.** The route is `DELETE /path` (no `:id`); send `id: ["1", "2", "3"]` in the body. Returns 400 if the value isn't an array.
+- **Validation hooks on `Restful`** are bound to the instance — call `this.repository` freely inside `validate()`. Plain controller validators don't get `this`.
+- **Don't import `routes.ts`.** Framework auto-loads it. See `register-route` for the rules.
+
+## See also
+
+- [`register-route/SKILL.md`](../register-route/SKILL.md) — the wider router surface (`group`, `prefix`, plain verbs).
+- [`create-controller/SKILL.md`](../create-controller/SKILL.md) — what the chain's handlers look like.
+- [`define-resource/SKILL.md`](../define-resource/SKILL.md) — wire shape for the records the chain returns.
+- [`warlock-conventions/SKILL.md`](../warlock-conventions/SKILL.md) — controller/service/repository layering rules.