@warlock.js/core 5.30.0 → 5.31.0

package/skills/write-seeder/SKILL.md

@@ -52,26 +52,26 @@ npx warlock seed --drop=default-roles       # undo just one seeder's records
 
 ```ts
 type Seeder = {
-  name: string;                                // required, used as the registry key
-  enabled?: boolean;                            // default true — set false to skip
-  description?: string;                         // shown in --list output
-  dependsOn?: string[];                         // names of seeds that must run first
-  once?: boolean;                               // skip if a row exists in the `seeds` table
-  order?: number;                               // sort key — lower runs first
-  batchSize?: number;                           // documented; not enforced by the manager
-  run(ctx: SeedContext): Promise<SeedResult | void>;   // your work
+  name: string; // required, used as the registry key
+  enabled?: boolean; // default true — set false to skip
+  description?: string; // shown in --list output
+  dependsOn?: string[]; // names of seeds that must run first
+  once?: boolean; // skip if a row exists in the `seeds` table
+  order?: number; // sort key — lower runs first
+  batchSize?: number; // documented; not enforced by the manager
+  run(ctx: SeedContext): Promise<SeedResult | void>; // your work
 };
 
 type SeedContext = {
-  track: Track;                                 // register created records for --drop
-  now: SeedClock;                               // injectable clock — () => Date, default () => new Date()
-  batchSize: number;                            // from the seeder's batchSize (0 when unset)
+  track: Track; // register created records for --drop
+  now: SeedClock; // injectable clock — () => Date, default () => new Date()
+  batchSize: number; // from the seeder's batchSize (0 when unset)
 };
 
 type SeedClock = () => Date;
 
 type SeedResult = {
-  recordsCreated: number;                       // OPTIONAL fallback when nothing was tracked
+  recordsCreated: number; // OPTIONAL fallback when nothing was tracked
 };
 ```
 
@@ -88,7 +88,7 @@ async run({ track, now }) {
 }
 ```
 
-Inject a fixed clock for deterministic tests or historical back-fills — pass `clock` to `SeedersManager` (`new SeedersManager({ clock: () => new Date("2020-01-01") })`) or, programmatically, to `seedCommandAction(options, { clock })`. Pinning the clock makes every timestamp in the run — seed data *and* the `seeds` log — resolve to that one value.
+Inject a fixed clock for deterministic tests or historical back-fills — pass `clock` to `SeedersManager` (`new SeedersManager({ clock: () => new Date("2020-01-01") })`) or, programmatically, to `seedCommandAction(options, { clock })`. Pinning the clock makes every timestamp in the run — seed data _and_ the `seeds` log — resolve to that one value.
 
 ## `batchSize` — bulk-insert hint
 
@@ -108,9 +108,9 @@ The manager doesn't act on `batchSize` itself — it only hands the value throug
 `track` is how a seed tells the framework which rows it created, so `--drop` can undo them. It has three forms, and **every form returns its first argument** so you can wrap a `create()` call inline:
 
 ```ts
-track(model)                 // single model — reads model.getTableName() + model.id
-track([modelA, modelB])      // bulk — array of models
-track("legacy_table", id)    // raw escape hatch — table name + id, no model
+track(model); // single model — reads model.getTableName() + model.id
+track([modelA, modelB]); // bulk — array of models
+track("legacy_table", id); // raw escape hatch — table name + id, no model
 ```
 
 ```ts
@@ -139,6 +139,7 @@ src/app/
 ```
 
 A seed file that doesn't export a default `Seeder` throws at discovery time:
+
 > `Seeder file <relative> does not export a default seeder.`
 
 Filename convention is `<name>.seed.ts` but the loader doesn't enforce it — any `.ts` inside a `seeds/` folder is picked up. Sticking to the suffix keeps things grep-able.
@@ -169,12 +170,12 @@ Use `once: true` for irreversible "starter" data (the framework's default `roles
 
 Every record you `track()` is written to a `seed_records` table (created on first run via `SeedRecordsTableMigration`):
 
-| Column     | Meaning                                  |
-| ---------- | ---------------------------------------- |
-| `seeder`   | Owning seeder's `name`                   |
-| `table`    | Table the tracked record lives in        |
-| `recordId` | Primary key of the tracked record        |
-| `runAt`    | Wall time the reference was recorded      |
+| Column     | Meaning                              |
+| ---------- | ------------------------------------ |
+| `seeder`   | Owning seeder's `name`               |
+| `table`    | Table the tracked record lives in    |
+| `recordId` | Primary key of the tracked record    |
+| `runAt`    | Wall time the reference was recorded |
 
 `warlock seed --drop` reads those refs and undoes the seed:
 
@@ -191,7 +192,7 @@ What it does, inside a single transaction:
 
 Only **tracked** rows are deleted — records you created without `track()` (or rows added by hand) are untouched. A seed whose `run()` never calls `track()` can't be undone with `--drop`; it has nothing to delete and its log row stays.
 
-`--drop` vs `--fresh`: `--fresh` is the blunt reset (truncates *every* table); `--drop` is surgical (only what a seed tracked). Reach for `--drop` when you want to re-run one seeder without nuking the whole DB.
+`--drop` vs `--fresh`: `--fresh` is the blunt reset (truncates _every_ table); `--drop` is surgical (only what a seed tracked). Reach for `--drop` when you want to re-run one seeder without nuking the whole DB.
 
 ## Ordering
 
@@ -204,7 +205,7 @@ seeder({
 
 seeder({
   name: "default-admin-user",
-  order: 20,         // runs AFTER user-roles (which created the roles it references)
+  order: 20, // runs AFTER user-roles (which created the roles it references)
   // ...
 });
 ```
@@ -213,20 +214,33 @@ The manager sorts by `order` ascending — lower runs first. Seeds without an `o
 
 ### `dependsOn` — topological order
 
-`dependsOn: ["user-roles"]` is **resolved** by the manager: it topologically sorts seeders so every dependency runs before its dependents, *layered over* the numeric `order` tie-break. Among seeders whose dependencies are already satisfied, the lowest `order` (then registration order) runs first.
+`dependsOn: ["user-roles"]` is **resolved** by the manager: it topologically sorts seeders so every dependency runs before its dependents, _layered over_ the numeric `order` tie-break. Among seeders whose dependencies are already satisfied, the lowest `order` (then registration order) runs first.
 
 ```ts
-seeder({ name: "roles", order: 20, async run() { /* ... */ } });
-seeder({ name: "admin-user", dependsOn: ["roles"], order: 10, async run() { /* ... */ } });
+seeder({
+  name: "roles",
+  order: 20,
+  async run() {
+    /* ... */
+  },
+});
+seeder({
+  name: "admin-user",
+  dependsOn: ["roles"],
+  order: 10,
+  async run() {
+    /* ... */
+  },
+});
 // → roles runs FIRST despite its higher order, because admin-user depends on it.
 ```
 
 Two ways it fails loudly:
 
-- **Unknown dependency** — `dependsOn` names a seeder that isn't registered (or is `enabled: false`, since disabled seeds are filtered out *before* resolution) → `UnknownSeederDependencyError`.
+- **Unknown dependency** — `dependsOn` names a seeder that isn't registered (or is `enabled: false`, since disabled seeds are filtered out _before_ resolution) → `UnknownSeederDependencyError`.
 - **Cycle** — `a → b → a` → `SeederDependencyCycleError` (the message includes the cycle path).
 
-Use `dependsOn` to express *hard* ordering constraints and `order` for soft sequencing within a dependency layer.
+Use `dependsOn` to express _hard_ ordering constraints and `order` for soft sequencing within a dependency layer.
 
 ## Transactions
 
@@ -234,7 +248,7 @@ By default, each seed runs inside a transaction. The manager wraps `run({ track
 
 ```ts
 const result = withTransaction
-  ? await transaction(runSeeder)   // run() + seed_records writes, atomically
+  ? await transaction(runSeeder) // run() + seed_records writes, atomically
   : await runSeeder();
 ```
 
@@ -265,7 +279,7 @@ export default seeder({
     for (const data of seeds) {
       const existing = await Currency.first({ code: data.code });
       if (existing) continue;
-      track(await Currency.create(data));   // count auto-derived from track()
+      track(await Currency.create(data)); // count auto-derived from track()
     }
   },
 });
@@ -283,7 +297,7 @@ import { User } from "../models/user";
 export default seeder({
   name: "default-admin",
   description: "Insert the seed admin user",
-  once: true,                   // never re-run
+  once: true, // never re-run
   dependsOn: ["default-roles"], // roles must exist first
   async run({ track }) {
     const adminRole = await Role.first({ slug: "admin" });

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"}