@warlock.js/cascade 5.19.1 → 5.21.0

package/skills/subscribe-to-model-events/SKILL.md

@@ -1,148 +1,148 @@
----
-name: subscribe-to-model-events
-description: "Use model events in @warlock.js/cascade; use when you need to subscribe to model events."
----
-
-# Use model events
-
-Every meaningful moment in a model's lifecycle — about to validate, about to save, just saved, just deleted — fires an event. Subscribe to hook in cross-cutting behavior without scattering it across every service.
-
-## Subscribing — per-model
-
-```ts
-User.on("saved", async (user) => {
-  await searchIndex.upsert({ id: user.id, name: user.get("name") });
-});
-
-User.on("deleted", async (user) => {
-  await searchIndex.remove(user.id);
-});
-```
-
-Listeners are async-aware — the model's persistence awaits the listener before moving on. A listener that throws during a pre-write event (`saving` / `creating` / `updating` / `validating`) aborts the operation; the error propagates to the caller.
-
-## The full event catalog
-
-The events fire in this order. The **gerund** form (`saving`, `creating`) is the "before" hook — there is no `beforeSave` alias.
-
-| Event | Fires |
-| --- | --- |
-| `saving` | Before validation, on every `save()` (both insert and update paths) |
-| `validating` / `validated` | Around schema validation |
-| `creating` | Before a new record is inserted (first save) |
-| `updating` | Before an existing record's update is written |
-| `saved` | After a successful write (any branch — insert or update) |
-| `created` | After a new record is inserted |
-| `updated` | After an existing record's update is written |
-| `deleting` / `deleted` | Before / after the delete strategy runs |
-| `restoring` / `restored` | Before / after a soft-deleted or trashed record is restored |
-| `fetching` / `fetched` / `hydrating` | Around reads / instance hydration |
-
-`saving` fires for both inserts and updates; `creating` / `updating` narrow to the branch. So `saved` always fires; exactly one of `created` / `updated` follows.
-
-## Listener signature
-
-```ts
-User.on("saving", async (user, context) => {
-  // user:    the User instance about to be persisted
-  // context: { isInsert, options, mode } for `saving`; varies per event
-});
-```
-
-The first argument is the model instance. The second carries event context (for `saving`: whether it's an insert, the `save()` options, and the mode).
-
-## Throwing to abort
-
-A listener on a pre-write event that throws stops the lifecycle — the save / delete never completes and the error propagates:
-
-```ts
-User.on("saving", async (user) => {
-  if (user.isDirty("email") && (await emailIsBlacklisted(user.get("email")))) {
-    throw new Error("Email domain is blacklisted");
-  }
-});
-```
-
-Pair with `isDirty()` from [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) so the listener only runs its expensive check when the relevant field changed.
-
-## Global listeners — across all models
-
-For framework-level concerns (audit log, observability, cache invalidation), subscribe on the base `Model` — the listener runs for every model:
-
-```ts
-import { Model } from "@warlock.js/cascade";
-
-Model.on("saved", async (instance) => {
-  await audit.log("save", instance.constructor.name, instance.id, instance.getDirtyColumns());
-});
-```
-
-Filter by `instance.constructor.name === "User"` when you only care about specific models, or register per-model handlers when the scope is narrow. (`Model.globalEvents()` returns the underlying global emitter if you need direct access.)
-
-## `off()` to unsubscribe
-
-```ts
-const handler = async (user) => {
-  /* ... */
-};
-const unsubscribe = User.on("saved", handler);
-
-// later — either:
-unsubscribe();
-// or:
-User.off("saved", handler);
-```
-
-`on()` also returns an unsubscribe function. Mostly useful in tests where you want to temporarily swap behavior.
-
-## Common patterns
-
-### Audit log (combined with dirty tracking)
-
-```ts
-Model.on("updated", async (instance) => {
-  const changes = instance.getDirtyColumnsWithValues();
-  if (Object.keys(changes).length === 0) {
-    return;
-  }
-
-  await AuditLog.create({
-    model: instance.constructor.name,
-    record_id: instance.id,
-    changes,
-    saved_at: new Date(),
-  });
-});
-```
-
-Use `updated` (not `saved`) when you only want change diffs — `getDirtyColumnsWithValues()` is still populated in the post-write events because the tracker resets *after* they fire.
-
-### Cache invalidation
-
-```ts
-User.on("saved", async (user) => {
-  await cache.tags([`user.${user.id}`]).invalidate();
-});
-
-User.on("deleted", async (user) => {
-  await cache.tags([`user.${user.id}`]).invalidate();
-});
-```
-
-See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md).
-
-### Side effects that must only fire after commit
-
-For external side effects (queues, emails) that must only fire if a surrounding transaction commits, don't run them in the `saved` handler — write to an outbox table and dispatch from a worker after commit.
-
-## Things NOT to do
-
-- Don't reach for `beforeSave` / `destroying` / `destroyed` — they don't exist. The hooks are `saving` (pre-save) and `deleting` / `deleted`.
-- Don't run long external work (HTTP calls, queue dispatches) directly in `saving` / `saved` handlers — inside a transaction they extend the lock. Use an outbox table.
-- Don't mutate the model's own fields in `saved` and expect them to persist. The write already happened; mutations here are in-memory only. Use `saving` for pre-persist mutation.
-- Don't subscribe inside a function that runs on every request. Register handlers once at startup, in a dedicated init file.
-
-## See also
-
-- [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) — `isDirty` / `getDirtyColumnsWithValues` for "only run if this field changed"
-- [`@warlock.js/cascade/configure-delete-strategy/SKILL.md`](@warlock.js/cascade/configure-delete-strategy/SKILL.md) — `deleting` / `deleted` / `restored` around delete strategies
+---
+name: subscribe-to-model-events
+description: 'Hook into model lifecycle events — `saving` / `saved`, `creating` / `created`, `updating` / `updated`, `validating` / `validated`, `deleting` / `deleted`, `restoring` / `restored`, `fetching` / `fetched`. Per-model `Model.on(event, fn)` or global via `Model.globalEvents()`. Triggers: `Model.on`, `Model.off`, `saving`, `saved`, `created`, `updated`, `deleting`, `deleted`, `restored`; "audit log on save", "notify on change", "denormalize into search index"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: dirty tracking — `@warlock.js/cascade/track-changes/SKILL.md`; competing libs `mongoose` middleware, `typeorm` subscribers, `prisma` extensions.'
+---
+
+# Use model events
+
+Every meaningful moment in a model's lifecycle — about to validate, about to save, just saved, just deleted — fires an event. Subscribe to hook in cross-cutting behavior without scattering it across every service.
+
+## Subscribing — per-model
+
+```ts
+User.on("saved", async (user) => {
+  await searchIndex.upsert({ id: user.id, name: user.get("name") });
+});
+
+User.on("deleted", async (user) => {
+  await searchIndex.remove(user.id);
+});
+```
+
+Listeners are async-aware — the model's persistence awaits the listener before moving on. A listener that throws during a pre-write event (`saving` / `creating` / `updating` / `validating`) aborts the operation; the error propagates to the caller.
+
+## The full event catalog
+
+The events fire in this order. The **gerund** form (`saving`, `creating`) is the "before" hook — there is no `beforeSave` alias.
+
+| Event | Fires |
+| --- | --- |
+| `saving` | Before validation, on every `save()` (both insert and update paths) |
+| `validating` / `validated` | Around schema validation |
+| `creating` | Before a new record is inserted (first save) |
+| `updating` | Before an existing record's update is written |
+| `saved` | After a successful write (any branch — insert or update) |
+| `created` | After a new record is inserted |
+| `updated` | After an existing record's update is written |
+| `deleting` / `deleted` | Before / after the delete strategy runs |
+| `restoring` / `restored` | Before / after a soft-deleted or trashed record is restored |
+| `fetching` / `fetched` / `hydrating` | Around reads / instance hydration |
+
+`saving` fires for both inserts and updates; `creating` / `updating` narrow to the branch. So `saved` always fires; exactly one of `created` / `updated` follows.
+
+## Listener signature
+
+```ts
+User.on("saving", async (user, context) => {
+  // user:    the User instance about to be persisted
+  // context: { isInsert, options, mode } for `saving`; varies per event
+});
+```
+
+The first argument is the model instance. The second carries event context (for `saving`: whether it's an insert, the `save()` options, and the mode).
+
+## Throwing to abort
+
+A listener on a pre-write event that throws stops the lifecycle — the save / delete never completes and the error propagates:
+
+```ts
+User.on("saving", async (user) => {
+  if (user.isDirty("email") && (await emailIsBlacklisted(user.get("email")))) {
+    throw new Error("Email domain is blacklisted");
+  }
+});
+```
+
+Pair with `isDirty()` from [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) so the listener only runs its expensive check when the relevant field changed.
+
+## Global listeners — across all models
+
+For framework-level concerns (audit log, observability, cache invalidation), subscribe on the base `Model` — the listener runs for every model:
+
+```ts
+import { Model } from "@warlock.js/cascade";
+
+Model.on("saved", async (instance) => {
+  await audit.log("save", instance.constructor.name, instance.id, instance.getDirtyColumns());
+});
+```
+
+Filter by `instance.constructor.name === "User"` when you only care about specific models, or register per-model handlers when the scope is narrow. (`Model.globalEvents()` returns the underlying global emitter if you need direct access.)
+
+## `off()` to unsubscribe
+
+```ts
+const handler = async (user) => {
+  /* ... */
+};
+const unsubscribe = User.on("saved", handler);
+
+// later — either:
+unsubscribe();
+// or:
+User.off("saved", handler);
+```
+
+`on()` also returns an unsubscribe function. Mostly useful in tests where you want to temporarily swap behavior.
+
+## Common patterns
+
+### Audit log (combined with dirty tracking)
+
+```ts
+Model.on("updated", async (instance) => {
+  const changes = instance.getDirtyColumnsWithValues();
+  if (Object.keys(changes).length === 0) {
+    return;
+  }
+
+  await AuditLog.create({
+    model: instance.constructor.name,
+    record_id: instance.id,
+    changes,
+    saved_at: new Date(),
+  });
+});
+```
+
+Use `updated` (not `saved`) when you only want change diffs — `getDirtyColumnsWithValues()` is still populated in the post-write events because the tracker resets *after* they fire.
+
+### Cache invalidation
+
+```ts
+User.on("saved", async (user) => {
+  await cache.tags([`user.${user.id}`]).invalidate();
+});
+
+User.on("deleted", async (user) => {
+  await cache.tags([`user.${user.id}`]).invalidate();
+});
+```
+
+See [`@warlock.js/cache/use-cache-tags/SKILL.md`](@warlock.js/cache/use-cache-tags/SKILL.md).
+
+### Side effects that must only fire after commit
+
+For external side effects (queues, emails) that must only fire if a surrounding transaction commits, don't run them in the `saved` handler — write to an outbox table and dispatch from a worker after commit.
+
+## Things NOT to do
+
+- Don't reach for `beforeSave` / `destroying` / `destroyed` — they don't exist. The hooks are `saving` (pre-save) and `deleting` / `deleted`.
+- Don't run long external work (HTTP calls, queue dispatches) directly in `saving` / `saved` handlers — inside a transaction they extend the lock. Use an outbox table.
+- Don't mutate the model's own fields in `saved` and expect them to persist. The write already happened; mutations here are in-memory only. Use `saving` for pre-persist mutation.
+- Don't subscribe inside a function that runs on every request. Register handlers once at startup, in a dedicated init file.
+
+## See also
+
+- [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) — `isDirty` / `getDirtyColumnsWithValues` for "only run if this field changed"
+- [`@warlock.js/cascade/configure-delete-strategy/SKILL.md`](@warlock.js/cascade/configure-delete-strategy/SKILL.md) — `deleting` / `deleted` / `restored` around delete strategies

package/skills/track-changes/SKILL.md

@@ -1,127 +1,127 @@
----
-name: track-changes
-description: "Track changes in @warlock.js/cascade; use when you need to track changes."
----
-
-# Track changes
-
-Every Cascade model carries a dirty tracker that records which fields you've changed since the model was loaded (or since the last `save()`). The tracker is the source of truth for "what would change if I save now."
-
-## The main reads
-
-```ts
-user.hasChanges();           // boolean — any field changed (or removed)?
-user.isDirty("email");       // boolean — specifically this column?
-
-user.getDirtyColumns();      // string[] — names of changed columns
-user.getRemovedColumns();    // string[] — columns explicitly unset since load
-
-user.getDirtyColumnsWithValues();
-// Record<string, { oldValue, newValue }> — the full diff, old + new per column
-```
-
-`isDirty` takes **one** column. To check several, ask `getDirtyColumns()` once and test membership (see the multi-field section below).
-
-## Conditional logic before save
-
-```ts
-if (user.isDirty("email")) {
-  const { oldValue } = user.getDirtyColumnsWithValues().email;
-  await mailer.sendEmailChangeNotice(oldValue);
-}
-
-await user.save();
-```
-
-The classic shape — only fire the side effect if the field actually changed. The pre-mutation value comes from `getDirtyColumnsWithValues()[column].oldValue`.
-
-## Diff for an audit log
-
-```ts
-const changes = user.getDirtyColumnsWithValues();
-// e.g. { name: { oldValue: "Ada", newValue: "Augusta Ada King" } }
-
-await AuditLog.create({
-  user_id: user.id,
-  before: Object.fromEntries(
-    Object.entries(changes).map(([field, { oldValue }]) => [field, oldValue]),
-  ),
-  after: Object.fromEntries(
-    Object.entries(changes).map(([field, { newValue }]) => [field, newValue]),
-  ),
-  changed_at: new Date(),
-});
-```
-
-`getDirtyColumnsWithValues()` hands you old and new together, so you never need a second call to read the prior value.
-
-## After save — tracker resets
-
-```ts
-user.set("name", "Augusta");
-user.isDirty("name");        // true
-await user.save();
-user.isDirty("name");        // false — tracker reset to the just-saved state
-```
-
-`save()` resets the tracker's baseline to the persisted state. Subsequent `isDirty()` checks measure changes since the last `save()`, not since the original load.
-
-## Multi-field check
-
-`isDirty` is single-column. For "did any of these change?", read the dirty set once:
-
-```ts
-const dirty = new Set(user.getDirtyColumns());
-const billingTouched = ["billing_address", "billing_city", "billing_zip"].some((field) =>
-  dirty.has(field),
-);
-
-if (billingTouched) {
-  await revalidateBillingAddress(user);
-}
-```
-
-## Tracker vs `.get()`
-
-- `user.get("email")` — the **current** value (post-mutation if you called `.set` / `.merge`)
-- `user.getDirtyColumnsWithValues().email?.oldValue` — the **pre-mutation** value (whatever the DB had)
-- `user.getDirtyColumns()` — the **changed field names** (string array)
-- `user.getDirtyColumnsWithValues()` — the **full diff** (old + new per changed field)
-
-If you need both old and new together:
-
-```ts
-const dirty = user.getDirtyColumnsWithValues();
-for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
-  // ... log, validate, conditionally re-route
-}
-```
-
-## How a merge decides what changed
-
-`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
-
-```ts
-// plain object → merged key-by-key, siblings survive
-user.merge({ profile: { age: 26 } });     // profile.city untouched
-user.getDirtyColumns();                    // ["profile.age"]
-
-// Date → replaced, not merged
-conversation.merge({ lastOutboundAt: new Date() });
-conversation.getDirtyColumns();            // ["lastOutboundAt"]
-```
-
-:::note[Fixed in 4.9.1]
-Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
-:::
-
-## Things NOT to do
-
-- Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.
-- Don't compare `user.get(field) === oldValue` for change detection — call `isDirty(field)` instead. The tracker uses identity-aware comparison appropriate to the column type (deep-equal for objects/arrays).
-- Don't expect dirty tracking on relations. The tracker covers columns only. For relation changes, use lifecycle events or compare counts.
-
-## See also
-
-- [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md) — combining with `saved` / `saving` for cross-cutting behavior
-- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — the `.set` / `.merge` / `.save` idioms that stage changes
+---
+name: track-changes
+description: 'Inspect a model''s pending changes — `hasChanges()` (any field dirty?), `isDirty(column)` (one column), `getDirtyColumns()` (changed field names), `getDirtyColumnsWithValues()` (old + new per field), `getRemovedColumns()` (unset fields). Triggers: `hasChanges`, `isDirty`, `getDirtyColumns`, `getDirtyColumnsWithValues`, `getRemovedColumns`; "only run if email changed", "diff for an audit log", "what fields are dirty", "compare old vs new value"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: hooking into save — `@warlock.js/cascade/subscribe-to-model-events/SKILL.md`; update idioms — `@warlock.js/cascade/define-model/SKILL.md`; competing libs `mongoose` `isModified` / `modifiedPaths`, `typeorm` change detection.'
+---
+
+# Track changes
+
+Every Cascade model carries a dirty tracker that records which fields you've changed since the model was loaded (or since the last `save()`). The tracker is the source of truth for "what would change if I save now."
+
+## The main reads
+
+```ts
+user.hasChanges();           // boolean — any field changed (or removed)?
+user.isDirty("email");       // boolean — specifically this column?
+
+user.getDirtyColumns();      // string[] — names of changed columns
+user.getRemovedColumns();    // string[] — columns explicitly unset since load
+
+user.getDirtyColumnsWithValues();
+// Record<string, { oldValue, newValue }> — the full diff, old + new per column
+```
+
+`isDirty` takes **one** column. To check several, ask `getDirtyColumns()` once and test membership (see the multi-field section below).
+
+## Conditional logic before save
+
+```ts
+if (user.isDirty("email")) {
+  const { oldValue } = user.getDirtyColumnsWithValues().email;
+  await mailer.sendEmailChangeNotice(oldValue);
+}
+
+await user.save();
+```
+
+The classic shape — only fire the side effect if the field actually changed. The pre-mutation value comes from `getDirtyColumnsWithValues()[column].oldValue`.
+
+## Diff for an audit log
+
+```ts
+const changes = user.getDirtyColumnsWithValues();
+// e.g. { name: { oldValue: "Ada", newValue: "Augusta Ada King" } }
+
+await AuditLog.create({
+  user_id: user.id,
+  before: Object.fromEntries(
+    Object.entries(changes).map(([field, { oldValue }]) => [field, oldValue]),
+  ),
+  after: Object.fromEntries(
+    Object.entries(changes).map(([field, { newValue }]) => [field, newValue]),
+  ),
+  changed_at: new Date(),
+});
+```
+
+`getDirtyColumnsWithValues()` hands you old and new together, so you never need a second call to read the prior value.
+
+## After save — tracker resets
+
+```ts
+user.set("name", "Augusta");
+user.isDirty("name");        // true
+await user.save();
+user.isDirty("name");        // false — tracker reset to the just-saved state
+```
+
+`save()` resets the tracker's baseline to the persisted state. Subsequent `isDirty()` checks measure changes since the last `save()`, not since the original load.
+
+## Multi-field check
+
+`isDirty` is single-column. For "did any of these change?", read the dirty set once:
+
+```ts
+const dirty = new Set(user.getDirtyColumns());
+const billingTouched = ["billing_address", "billing_city", "billing_zip"].some((field) =>
+  dirty.has(field),
+);
+
+if (billingTouched) {
+  await revalidateBillingAddress(user);
+}
+```
+
+## Tracker vs `.get()`
+
+- `user.get("email")` — the **current** value (post-mutation if you called `.set` / `.merge`)
+- `user.getDirtyColumnsWithValues().email?.oldValue` — the **pre-mutation** value (whatever the DB had)
+- `user.getDirtyColumns()` — the **changed field names** (string array)
+- `user.getDirtyColumnsWithValues()` — the **full diff** (old + new per changed field)
+
+If you need both old and new together:
+
+```ts
+const dirty = user.getDirtyColumnsWithValues();
+for (const [field, { oldValue, newValue }] of Object.entries(dirty)) {
+  // ... log, validate, conditionally re-route
+}
+```
+
+## How a merge decides what changed
+
+`.merge()` deep-merges **plain objects only**. Every other value — primitives, arrays, and class instances such as `Date`, `Map`, `Set`, `RegExp` — **replaces** the target outright.
+
+```ts
+// plain object → merged key-by-key, siblings survive
+user.merge({ profile: { age: 26 } });     // profile.city untouched
+user.getDirtyColumns();                    // ["profile.age"]
+
+// Date → replaced, not merged
+conversation.merge({ lastOutboundAt: new Date() });
+conversation.getDirtyColumns();            // ["lastOutboundAt"]
+```
+
+:::note[Fixed in 4.9.1]
+Before 4.9.1 a `Date` merged over a column that **already held a `Date`** was silently dropped: the merge treated it as a mergeable container and recursed into it, and a `Date` has no own enumerable properties, so nothing was copied. The column never went dirty and `save()` returned `{ success: true, modifiedCount: 0 }` with no `UPDATE` issued. Writing into an empty column always worked, so only overwrites were affected. If you are on 4.9.0 or earlier, upgrade.
+:::
+
+## Things NOT to do
+
+- Don't use `hasChanges()` / `isDirty()` after `save()` to verify the save persisted. The tracker resets to clean on save — these become false regardless. Read back from the DB if you need verification.
+- Don't compare `user.get(field) === oldValue` for change detection — call `isDirty(field)` instead. The tracker uses identity-aware comparison appropriate to the column type (deep-equal for objects/arrays).
+- Don't expect dirty tracking on relations. The tracker covers columns only. For relation changes, use lifecycle events or compare counts.
+
+## See also
+
+- [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md) — combining with `saved` / `saving` for cross-cutting behavior
+- [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) — the `.set` / `.merge` / `.save` idioms that stage changes