@rudderjs/orm 1.5.0 → 1.7.0

package/README.md

@@ -195,7 +195,106 @@ await Comment.create({
 
 The discriminator stored in `{morphName}Type` defaults to the parent's class name (`'Post'`, `'Video'`). Override per-class with `static morphAlias = 'post'` to decouple persisted values from JS class names — useful for rename-safe storage. Once set and data exists, treat it as immutable. In dev mode (`NODE_ENV !== 'production'`), `morphTo` resolution checks the `types` list for duplicate discriminators and throws if two classes resolve to the same value.
 
-`belongsToMany` and polymorphic v1 limitations: pivot columns are not surfaced on read results (write side only), no `withTimestamps`, no `morphToMany` / `morphedByMany`, no fluent eager-load (`User.with('comments.commentable')`) — drop to the adapter (Prisma `include`) for those. Mutations on the deferred read query (`create`/`update`/`delete`/`insertMany`/`deleteAll`) throw — write through the related model directly.
+`belongsToMany` and polymorphic v1 limitations: pivot columns are not surfaced on read results (write side only), no `withTimestamps`, no fluent eager-load (`User.with('comments.commentable')`) — drop to the adapter (Prisma `include`) for that. Mutations on the deferred read query (`create`/`update`/`delete`/`insertMany`/`deleteAll`) throw — write through the related model directly. `morphToMany` / `morphedByMany` are supported with the same `attach` / `detach` / `sync` accessor as `belongsToMany`, plus discriminator-scoped pivot reads/writes — see the [polymorphic many-to-many guide](https://rudderjs.com/docs/database/models#polymorphic-many-to-many-morphtomany-morphedbymany).
+
+### Filtering by relation predicate — `whereHas` / `whereDoesntHave` / `withWhereHas` / `whereBelongsTo`
+
+Filter a query by whether a relation has at least one matching row. The optional callback narrows the relation predicate further — chain plain `where()` calls inside it.
+
+```ts
+// Users with at least one post
+await User.whereHas('posts').get()
+
+// Users with at least one published post
+await User.whereHas('posts', q => q.where('published', true)).get()
+
+// Inverse — users with zero published posts
+await User.whereDoesntHave('posts', q => q.where('published', true)).get()
+
+// Filter AND eager-load under the same constraint (constrained eager-load
+// via the adapter's `withConstrained` when supported, falls back to plain
+// `with(relation)` otherwise — Drizzle today)
+await User.withWhereHas('posts', q => q.where('published', true)).get()
+
+// Sugar over `where(fk, parent.id)` — looks up the FK column from the
+// belongsTo declaration. Pass the relation name when the calling class
+// has multiple belongsTo to the same parent.
+await Post.whereBelongsTo(user).get()
+await Comment.whereBelongsTo(post, 'post').get()
+```
+
+Supported relation types: `hasMany`, `hasOne`, `belongsTo`, `belongsToMany`, `morphMany`, `morphOne`, `morphToMany`, `morphedByMany`. **`morphTo` is intentionally not supported** — the related table is dynamic, so a single subquery can't represent it. Filter on the `{morphName}Id` / `{morphName}Type` columns directly when you need that semantic.
+
+**Adapter notes:**
+
+- **Prisma** uses native `some` / `none` filters for direct relations (`hasMany`/`hasOne`/`belongsTo`) — those relations must be declared in `schema.prisma` with the same name. Polymorphic and pivot relations route through a 2-step lookup (related → pivot → IN list) so they work without a Prisma-declared relation.
+- **Drizzle** uses correlated `EXISTS (...)` / `NOT EXISTS (...)` subqueries. Every related table referenced from a `whereHas` call must be registered via `tables: { ... }` on `drizzle()` config or `DrizzleTableRegistry.register(name, table)`.
+- **`withWhereHas`** uses `withConstrained` when the adapter implements it (Prisma → nested `include: { rel: { where } }`). The Drizzle adapter doesn't yet — `withWhereHas` falls back to plain `with(relation)` there.
+- **Nested `whereHas` inside the constrain callback throws** — recursive predicates are deferred to v2. Filter on flat columns inside the callback for now.
+- **Soft deletes inside the relation predicate** — apply `q.where('deletedAt', null)` explicitly inside the constrain callback when needed.
+
+### Aggregate eager loading — `withCount` / `withSum` / `withMin` / `withMax` / `withAvg` / `withExists`
+
+Eager-load aggregates of related rows alongside the parent in a single query. The result is stamped onto each parent under a deterministic alias (`<relation><Verb><Column>`) so admin tables, dashboards, and any list page can render counts / sums next to each row without N+1.
+
+```ts
+// Counts: stamps user.postsCount on each row
+await User.query().withCount('posts').get()
+
+// Sum / min / max / avg of a related column — stamps postsSumViews etc.
+await User.query().withSum('posts', 'views').get()
+await Login.query().withMax('sessions', 'createdAt').get()
+
+// Boolean — stamps subscriptionExists (true/false)
+await User.query().withExists('subscription').get()
+
+// Multiple at once
+await User.query()
+  .withCount('posts')
+  .withSum('orders', 'total')
+  .paginate(1)
+```
+
+**Constraint callbacks (map form)** — narrow what counts as a "matching" row, optionally aliasing the result key:
+
+```ts
+await User.query()
+  .withCount({ posts: q => q.where('published', true).as('publishedPosts') })
+  .get()
+// → user.publishedPostsCount
+
+await User.query()
+  .withSum({
+    orders: { column: 'total', constraint: q => q.where('status', 'paid') },
+  })
+  .get()
+// → user.ordersSumTotal
+```
+
+**Per-instance variants** — `loadCount` / `loadExists` / `loadSum` / `loadMin` / `loadMax` / `loadAvg` mutate a single instance in place. Use these when you've already fetched one parent and need the aggregate on demand. For batched loads on a list, prefer `Model.query().withCount(...)` on the parent query.
+
+```ts
+const user = await User.find(1)
+await user!.loadCount('posts')
+console.log(user!.postsCount)
+```
+
+**`loadMissing(...names)`** — eager-load each named relation onto the instance only when the property is currently `null` / `undefined`. Skips relations that are already populated.
+
+```ts
+const user = await User.query().with('profile').first()
+// profile is already populated; only `posts` issues a query
+await user!.loadMissing('profile', 'posts')
+```
+
+**Notes:**
+
+- Aggregate columns are enumerable own-properties — they appear in `JSON.stringify(row)`, `Object.entries(row)`, and `{ ...row }` spreads. They're tagged via a Symbol so `model.save()` strips them out before writing back to the DB.
+- **`withCount` on `belongsTo` throws** (every parent matches exactly one row, so the count is always 0 or 1). Use `withExists('relation')` to test presence, or query the inverse `hasMany` side.
+- **`withCount` on `morphTo` throws** — the related table is dynamic. Aggregate per-target by querying each target class separately.
+- Results are typed `unknown` at the property-access site — cast at the call site (`(user as { postsCount: number }).postsCount`) since the QB type doesn't track the injected aliases. The instance load path doesn't need a cast at the access site.
+- **Soft deletes** on the related model are applied automatically — the adapter ANDs `deleted_at IS NULL` into the aggregate subquery.
+- **Adapter behavior**: Prisma uses `_count.select` for direct count/exists (round-trip-saving) and a second-batch `groupBy` for polymorphic / pivot / numeric aggregates. Drizzle emits one correlated subselect per aggregate in the SELECT list, joining through the pivot table when present.
 
 ---
 
@@ -599,6 +698,58 @@ await Article.query().scope('byAuthor', userId).get()
 
 ---
 
+## Dirty Tracking
+
+Every Model instance keeps a snapshot of its attributes as of the last
+`hydrate()` / `save()` / `refresh()`. Use it to inspect what changed before
+or after persistence.
+
+```ts
+const user = await User.find(1)         // hydrated → not dirty
+user.email = 'new@x.com'
+user.isDirty()                          // → true
+user.isDirty('email')                   // → true
+user.isClean('name')                    // → true
+user.getDirty()                         // → { email: 'new@x.com' }
+user.getOriginal('email')               // → 'old@x.com'
+
+await user.save()
+user.isDirty()                          // → false (baseline reset)
+user.wasChanged()                       // → true
+user.wasChanged('email')                // → true
+user.getChanges()                       // → { email: 'new@x.com', updatedAt: ... }
+```
+
+| Method | Returns |
+|---|---|
+| `isDirty(key?)` | true when any (or the named) attribute has changed since the last save / load / refresh. |
+| `isClean(key?)` | inverse of `isDirty`. |
+| `wasChanged(key?)` | true when the most recent `save()` actually persisted a change to that attribute. Stays true until the next save / refresh. |
+| `getOriginal(key?)` | snapshot value(s) as of the last save / load / refresh. With a key, that single value; without, a full copy of the snapshot. |
+| `getChanges()` | diff of attributes that changed during the most recent `save()`. |
+| `getDirty()` | diff of attributes currently dirty (unsaved). |
+
+**Equality semantics.** Primitives use `===`. Dates compare by `getTime()`.
+Plain objects and arrays (typically `json` / `array` cast columns) compare
+by `JSON.stringify` — key-order sensitive, so `{ a: 1, b: 2 }` and
+`{ b: 2, a: 1 }` are considered different. This matches Eloquent's posture.
+
+**`refresh()` discards pending writes.** A `refresh()` re-reads the row,
+re-baselines `getOriginal()`, and clears `getChanges()`. Eloquent retains
+`wasChanged` past a refresh; we don't — refresh is "throw away pending
+state, re-read from DB."
+
+**`increment()` / `decrement()` re-baseline.** After an instance counter
+update, `isDirty('viewCount')` is `false` — the new value becomes the
+baseline. Counter updates are pure data-plane and intentionally don't
+fire observers (see `static increment` notes); dirty tracking matches.
+
+**`replicate()` clones are unsaved.** A replicated instance has values
+on it but an empty `getOriginal()`, so `isDirty()` is `true` until the
+clone is saved.
+
+---
+
 ## Soft Deletes
 
 ```ts
@@ -617,6 +768,52 @@ Post.query().onlyTrashed().get()   // only soft-deleted
 
 ---
 
+## Pruning
+
+Models can opt into `pnpm rudder model:prune` by declaring `static prunable()`. The runner walks the registered models and deletes everything the query returns, in chunks. Two modes:
+
+```ts
+import { Model } from '@rudderjs/orm'
+
+// Per-instance — observers fire, soft-deletes honored
+class Session extends Model {
+  static override table = 'sessions'
+  static prunable() { return this.where('expiresAt', '<', new Date()) }
+  static pruning(s: Session) { /* optional pre-delete hook */ }
+}
+
+// Bulk — single deleteAll() per chunk; no observers, no pruning() hook,
+// soft-deletes bypassed (mirrors the deleteAll() primitive)
+class FailedJob extends Model {
+  static override table = 'failed_jobs'
+  static override pruneMode = 'mass' as const
+  static prunable() { return this.where('failedAt', '<', new Date(Date.now() - 7 * 86_400_000)) }
+}
+```
+
+Run from the CLI:
+
+```bash
+pnpm rudder model:prune                          # prune everything
+pnpm rudder model:prune --pretend                # dry-run; runs count() only
+pnpm rudder model:prune --model=Session,FailedJob
+pnpm rudder model:prune --except=AuditLog
+pnpm rudder model:prune --chunk=500
+```
+
+Or schedule it from `routes/console.ts`:
+
+```ts
+scheduler.command('model:prune').daily()
+scheduler.command('model:prune --pretend').weeklyOn(0, '09:00')
+```
+
+`Prunable` (default) calls `instance.delete()` per row — observers fire, soft-deletes apply. `MassPrunable` (`pruneMode = 'mass'`) is faster but bypasses both. Index the columns your `prunable()` filter touches; the runner re-queries per chunk because deletions shift the offset. `pruning()` exceptions are logged and the run continues — one bad row doesn't abort the sweep.
+
+For programmatic use, `pruneModels({ models, except, chunk, pretend })` returns one `{ model, mode, count }` report per pruned model.
+
+---
+
 ## Observers
 
 Register lifecycle hooks on a model to transform data, log events, or cancel operations.
@@ -660,6 +857,34 @@ Article.on('deleting', (id) => { if (id === protectedId) return false })
 > Use `Model.create()`/`Model.update()`/`Model.delete()` to trigger events.
 > `Model.query().create()` does NOT fire events.
 
+### Quiet Events
+
+Persist, delete, or restore an instance without firing observers or
+listeners — useful inside seeders, observer cascades, or any path that
+shouldn't trigger lifecycle work twice.
+
+```ts
+const user = await User.find(1)
+user.email = 'new@x.com'
+await user.saveQuietly()         // persists, observers silent
+
+await user.deleteQuietly()       // removes / soft-deletes silently
+
+const trashed = await User.withTrashed().find(2)
+await trashed.restoreQuietly()   // clears deletedAt silently
+```
+
+Sugar over `Model.withoutEvents()` — `await ctor.withoutEvents(() => instance.save())`.
+
+**Per-class isolation.** Quiet ops mute only the *current* class.
+A `User.saveQuietly()` whose observer cascades into `Comment.delete()`
+still fires `Comment` observers — same posture as Eloquent's
+`saveQuietly`. Wrap the cascade in a broader `withoutEvents` block if
+you need full silence.
+
+`instance.restore()` (the non-quiet form) is also available — symmetric
+to `instance.delete()` — and fires `restoring` / `restored` normally.
+
 ---
 
 ## toJSON()

package/dist/aggregate.d.ts

@@ -0,0 +1,95 @@
+import type { AggregateFn, AggregateRequest, AggregateJoinShape, WhereClause } from '@rudderjs/contracts';
+import type { Model, RelationDefinition } from './index.js';
+/**
+ * Constraint callback for the map form of `withCount` / `withExists`. Receives
+ * an {@link AggregateConstraintBuilder} for narrow `where`/`orWhere`/`as`
+ * recording. Larger surface (`orderBy`, `limit`, terminals) is intentionally
+ * out of scope — the only ambiguous semantics in an aggregate context.
+ */
+export type AggregateConstraint = (q: AggregateConstraintBuilder) => AggregateConstraintBuilder;
+/**
+ * `where`/`orWhere`/`as` recorder passed to {@link AggregateConstraint}
+ * callbacks. Captures clauses for the adapter to AND into the aggregate
+ * subquery, plus an optional alias prefix override (`.as('publishedPosts')`).
+ */
+export declare class AggregateConstraintBuilder {
+    /** @internal */
+    readonly _wheres: WhereClause[];
+    /** @internal — alias prefix override; falls back to the relation name. */
+    _aliasPrefix?: string;
+    where(column: string, valueOrOperator: unknown, maybeValue?: unknown): this;
+    orWhere(column: string, valueOrOperator: unknown, maybeValue?: unknown): this;
+    /**
+     * Override the alias prefix used to stamp the aggregate column onto the
+     * result row. Default = relation name. The verb suffix (`Count`/`SumX`/etc.)
+     * is preserved, so `.as('publishedPosts')` on a `withCount` call yields
+     * `publishedPostsCount`.
+     *
+     * Required when calling the same `withCount` / `withSum` twice on different
+     * constraints — distinct aliases prevent the second from clobbering the first.
+     */
+    as(alias: string): this;
+}
+/** Map-form spec for `withSum` / `withMin` / `withMax` / `withAvg`. */
+export interface AggregateSumSpec {
+    column: string;
+    constraint?: AggregateConstraint;
+}
+/**
+ * Per-instance set of attribute keys that came from an aggregate eager-load,
+ * not from the underlying schema. Read by `Model._toData()` to skip these
+ * keys on writes and by callers that need to distinguish injected columns.
+ *
+ * Cross-realm-safe via `Symbol.for(...)` — distinct copies of `@rudderjs/orm`
+ * loaded by different module graphs share the same tag.
+ */
+export declare const AGGREGATES_SYMBOL: unique symbol;
+/** @internal — read or initialise the aggregate-key set on a Model instance. */
+export declare function aggregateKeysOf(instance: object): Set<string>;
+/**
+ * The verb suffix that distinguishes which aggregate is stamped on the parent.
+ * Combined with the relation name (or `.as(...)` override) to produce the
+ * final alias key — e.g. `posts` + `count` → `postsCount`,
+ * `posts` + sum of `views` → `postsSumViews`.
+ */
+export declare function aggregateSuffix(fn: AggregateFn, column?: string): string;
+export declare function aggregateAlias(fn: AggregateFn, baseAlias: string, column?: string): string;
+/**
+ * Build the {@link AggregateJoinShape} for a relation declared on `Parent`.
+ * Mirrors `_buildRelationPredicate` but emits the join-shape subset rather
+ * than the full {@link RelationExistencePredicate}. `morphTo` and `belongsTo`
+ * are rejected by the caller before reaching this function; everything else
+ * routes through.
+ */
+export declare function buildAggregateJoinShape(Parent: typeof Model, relation: string, def: Exclude<RelationDefinition, {
+    type: 'morphTo' | 'belongsTo';
+}>): AggregateJoinShape;
+type RelationsMapEntry = AggregateConstraint;
+type RelationsMap = Record<string, RelationsMapEntry>;
+/** Public entrypoint: normalize all `withCount(...)` overloads. */
+export declare function normalizeWithCount(Parent: typeof Model, arg: string | readonly string[] | RelationsMap): AggregateRequest[];
+/** Public entrypoint: normalize all `withExists(...)` overloads. */
+export declare function normalizeWithExists(Parent: typeof Model, arg: string | readonly string[]): AggregateRequest[];
+/** Public entrypoint: normalize all `withSum/withMin/withMax/withAvg(...)` overloads. */
+export declare function normalizeWithNumericAggregate(Parent: typeof Model, fn: 'sum' | 'min' | 'max' | 'avg', arg1: string | Record<string, AggregateSumSpec>, arg2?: string): AggregateRequest[];
+/**
+ * Implementation of `Model#loadCount` / `loadExists`. Mutates the instance
+ * in place; returns it for chaining at the call site.
+ */
+export declare function loadCountOrExists(instance: Model, fn: 'count' | 'exists', arg: string | readonly string[] | RelationsMap): Promise<void>;
+/**
+ * Implementation of `Model#loadSum` / `loadMin` / `loadMax` / `loadAvg`.
+ */
+export declare function loadNumericAggregate(instance: Model, fn: 'sum' | 'min' | 'max' | 'avg', relation: string | Record<string, AggregateSumSpec>, column?: string): Promise<void>;
+/**
+ * Implementation of `Model#loadMissing`. Loads each named relation onto the
+ * instance only when the property is currently `null` / `undefined`.
+ *
+ * Always uses `instance.related(name).get()` (the chainable QB form) — for
+ * `hasOne` / `belongsTo` / `morphOne` semantics the caller can `[0]` the
+ * resulting array if they know the relation is single-valued, or call
+ * `loadMissing` only on the *array* relations they care about.
+ */
+export declare function loadMissingRelations(instance: Model, names: readonly string[]): Promise<void>;
+export {};
+//# sourceMappingURL=aggregate.d.ts.map

package/dist/aggregate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aggregate.d.ts","sourceRoot":"","sources":["../src/aggregate.ts"],"names":[],"mappings":"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"}