@warlock.js/core 5.30.0 → 5.32.0

package/skills/write-use-case/SKILL.md

@@ -43,16 +43,16 @@ onExecuting → guards → schema → before → handler → after → onComplet
                                   └ retry + benchmark wrap the handler only ┘
 ```
 
-| Phase         | Signature                                                              | Notes                                                                            |
-| ------------- | --------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
-| `onExecuting` | `(ctx: UseCaseOnExecutingContext) => void`                            | Fires first (once). `ctx` carries `id`, `name`, `data`, `schema`, `startedAt`.    |
-| `guards`      | `(data: Readonly<Input>, ctx: Ctx) => void \| Promise<void>`          | Authorization / precondition checks. **Throw to abort.** Enrich `ctx`, don't mutate `data`. |
-| `schema`      | `ObjectValidator` (seal `v.object(...)`)                              | Runs after guards. Failures throw `BadSchemaUseCaseError` and skip the handler.   |
-| `before`      | `(data: Input, ctx) => Input \| Promise<Input>`                       | Runs after schema. Sequential — each return becomes the next's input.            |
-| `handler`     | `(data: Input, ctx) => Promise<Output>`                               | The work. Receives the post-`before` payload. Retry + benchmark wrap **this**.   |
-| `after`       | `(output: Output, ctx) => void \| Promise<void>`                      | Fire-and-forget side effects on success. Errors are logged, never re-thrown.     |
-| `onCompleted` | `(result: UseCaseResult<Output>) => void`                            | Lifecycle event with the full `UseCaseResult` snapshot.                          |
-| `onError`     | `(ctx: UseCaseErrorResult) => void`                                  | Lifecycle event with the error + execution metadata.                            |
+| Phase         | Signature                                                    | Notes                                                                                       |
+| ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
+| `onExecuting` | `(ctx: UseCaseOnExecutingContext) => void`                   | Fires first (once). `ctx` carries `id`, `name`, `data`, `schema`, `startedAt`.              |
+| `guards`      | `(data: Readonly<Input>, ctx: Ctx) => void \| Promise<void>` | Authorization / precondition checks. **Throw to abort.** Enrich `ctx`, don't mutate `data`. |
+| `schema`      | `ObjectValidator` (seal `v.object(...)`)                     | Runs after guards. Failures throw `BadSchemaUseCaseError` and skip the handler.             |
+| `before`      | `(data: Input, ctx) => Input \| Promise<Input>`              | Runs after schema. Sequential — each return becomes the next's input.                       |
+| `handler`     | `(data: Input, ctx) => Promise<Output>`                      | The work. Receives the post-`before` payload. Retry + benchmark wrap **this**.              |
+| `after`       | `(output: Output, ctx) => void \| Promise<void>`             | Fire-and-forget side effects on success. Errors are logged, never re-thrown.                |
+| `onCompleted` | `(result: UseCaseResult<Output>) => void`                    | Lifecycle event with the full `UseCaseResult` snapshot.                                     |
+| `onError`     | `(ctx: UseCaseErrorResult) => void`                          | Lifecycle event with the error + execution metadata.                                        |
 
 `ctx` is a `UseCaseContext` shared across every phase. With the optional `Ctx` generic (`useCase<Output, Input, MyCtx>`) it's typed end-to-end; guards write `ctx.currentUser`, the handler reads it.
 
@@ -60,8 +60,19 @@ onExecuting → guards → schema → before → handler → after → onComplet
 
 ```ts
 import type { RetryOptions } from "@mongez/reinforcements";
-
-type UseCase<Output, Input, Ctx = UseCaseContext> = {
+import type {
+  BenchmarkOptions,
+  UseCaseAfterMiddleware,
+  UseCaseBeforeMiddleware,
+  UseCaseContext,
+  UseCaseErrorResult,
+  UseCaseGuard,
+  UseCaseOnExecutingContext,
+  UseCaseResult,
+} from "@warlock.js/core";
+import type { ObjectValidator } from "@warlock.js/seal";
+
+type UseCase<Output, Input, Ctx extends UseCaseContext = UseCaseContext> = {
   name: string;
   description?: string;
   handler: (data: Input, ctx: Ctx) => Promise<Output>;
@@ -72,9 +83,11 @@ type UseCase<Output, Input, Ctx = UseCaseContext> = {
   onExecuting?: (ctx: UseCaseOnExecutingContext) => void;
   onCompleted?: (result: UseCaseResult<Output>) => void;
   onError?: (ctx: UseCaseErrorResult) => void;
-  retry?: RetryOptions;                 // from @mongez/reinforcements
+  retry?: RetryOptions; // from @mongez/reinforcements
   benchmark?: boolean | BenchmarkOptions;
-  broadcast?: boolean | { event?: string; output?: (output, result) => unknown };
+  broadcast?:
+    | boolean
+    | { event?: string; output?: (output: Output, result: UseCaseResult<Output>) => unknown };
 };
 ```
 
@@ -88,7 +101,7 @@ Defaults come from `config.get("use-cases")` (`src/config/use-cases.ts`); per-us
 export const flakyApiCallUseCase = useCase({
   name: "external.callFlakyApi",
   retry: {
-    attempts: 4,                         // initial try + 3 retries
+    attempts: 4, // initial try + 3 retries
     delay: 500,
     backoff: "exponential",
     shouldRetry: (error) => !(error instanceof ValidationError), // skip 4xx
@@ -121,7 +134,7 @@ export const createUserUseCase = useCase({
   name: "users.create",
   schema: createUserSchema,
   handler: async (data) => User.create(data),
-  broadcast: true,                       // → channel "users.create", payload = output as-is
+  broadcast: true, // → channel "users.create", payload = output as-is
 });
 
 // Project / rename to avoid leaking sensitive fields:
@@ -130,7 +143,7 @@ export const signupUseCase = useCase({
   schema: signupSchema,
   handler: async (data) => signupService(data),
   broadcast: {
-    event: "auth.signup",                // custom channel name (default = use case name)
+    event: "auth.signup", // custom channel name (default = use case name)
     output: (result) => ({ id: result.id, email: result.email }), // never the raw model
   },
 });
@@ -138,11 +151,12 @@ export const signupUseCase = useCase({
 
 ```ts
 // 2. Global config — the transport (HOW). src/config/use-cases.ts
+import type { UseCaseConfigurations } from "@warlock.js/core";
 import { heraldBroadcast } from "@warlock.js/herald";
 
 export default {
   broadcast: {
-    enabled: true,                       // global kill-switch
+    enabled: true, // global kill-switch
     channels: [heraldBroadcast({ broker: "default" })],
   },
 } satisfies UseCaseConfigurations;
@@ -244,8 +258,8 @@ Global listeners exist too — `globalUseCasesEvents.onExecuting(...)` / `onComp
 
 ```ts
 export default {
-  benchmark: true,                       // benchmark every handler by default
-  log: false,                            // per-step debug logging via @warlock.js/logger
+  benchmark: true, // benchmark every handler by default
+  log: false, // per-step debug logging via @warlock.js/logger
   history: { enabled: true, ttl: 3600, maxEntries: 100 },
   broadcast: { enabled: false, channels: [] },
 } satisfies UseCaseConfigurations;
@@ -255,8 +269,8 @@ export default {
 
 ```ts
 await placeOrderUseCase(input, {
-  id: "order-tracking-123",              // override auto-generated execution id
-  ctx: { currentUser: user },            // pre-populate context for guards
+  id: "order-tracking-123", // override auto-generated execution id
+  ctx: { currentUser: user }, // pre-populate context for guards
   onCompleted: (result) => log.debug("done", result.benchmarkResult),
   onError: ({ error }) => log.error("failed", error),
 });
@@ -266,10 +280,10 @@ Per-invocation callbacks fire first, then use-case-level, then globals. The retu
 
 ## Use case vs service vs controller
 
-| Layer      | What it owns                                                              | When to use                                |
-| ---------- | ------------------------------------------------------------------------ | ------------------------------------------ |
-| Controller | Pull from `request`, return via `response.<helper>()`                     | Always — the HTTP edge.                    |
-| Service    | One unit of work, plain async function, no observability magic           | Most CRUD; one or two model touches.       |
+| Layer      | What it owns                                                             | When to use                                                                                                         |
+| ---------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------- |
+| Controller | Pull from `request`, return via `response.<helper>()`                    | Always — the HTTP edge.                                                                                             |
+| Service    | One unit of work, plain async function, no observability magic           | Most CRUD; one or two model touches.                                                                                |
 | Use case   | Guards/validation/handler/after + retry + benchmark + broadcast + events | Cross-cutting concerns, multi-service orchestration, anything called from multiple transports (HTTP + CLI + queue). |
 
 Don't reach for `useCase` for a 5-line service — the ceremony outweighs the benefit.
@@ -292,4 +306,3 @@ For the plain-function flavour (`warlock generate.use-case <module>/<verb-noun>`
 
 - The `create-controller` topic — the usual next step: invoke this use case from an HTTP controller.
 - The `publish-message` topic of the `warlock-js-herald` skill — the message bus the `broadcast` adapter publishes to (cross-package).
-

package/esm/http/uploads/matches-if-none-match.mjs

@@ -1,13 +0,0 @@
-//#region ../../packages/core/src/http/uploads/matches-if-none-match.ts
-/**
-* Whether an `If-None-Match` header matches an entity tag (weak comparison,
-* RFC 9110 §13.1.2): `*`, or any listed tag equal to `etag` once `W/` is dropped.
-*/
-function matchesIfNoneMatch(header, etag) {
-	if (typeof header !== "string" || header === "") return false;
-	return header.split(",").map((tag) => tag.trim().replace(/^W\//, "")).some((tag) => tag === "*" || tag === etag);
-}
-
-//#endregion
-export { matchesIfNoneMatch };
-//# sourceMappingURL=matches-if-none-match.mjs.map

package/esm/http/uploads/matches-if-none-match.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"matches-if-none-match.mjs","names":[],"sources":["../../../../../../../../../packages/core/src/http/uploads/matches-if-none-match.ts"],"sourcesContent":["/**\n * Whether an `If-None-Match` header matches an entity tag (weak comparison,\n * RFC 9110 §13.1.2): `*`, or any listed tag equal to `etag` once `W/` is dropped.\n */\nexport function matchesIfNoneMatch(header: unknown, etag: string): boolean {\n  if (typeof header !== \"string\" || header === \"\") return false;\n\n  return header\n    .split(\",\")\n    .map((tag) => tag.trim().replace(/^W\\//, \"\"))\n    .some((tag) => tag === \"*\" || tag === etag);\n}\n"],"mappings":";;;;;AAIA,SAAgB,mBAAmB,QAAiB,MAAuB;CACzE,IAAI,OAAO,WAAW,YAAY,WAAW,IAAI,OAAO;CAExD,OAAO,OACJ,MAAM,GAAG,CAAC,CACV,KAAK,QAAQ,IAAI,KAAK,CAAC,CAAC,QAAQ,QAAQ,EAAE,CAAC,CAAC,CAC5C,MAAM,QAAQ,QAAQ,OAAO,QAAQ,IAAI;AAC9C"}