@warlock.js/cascade 4.0.171 → 4.1.1

package/llms.txt

@@ -0,0 +1,23 @@
+# Warlock Cascade
+
+> Package: `@warlock.js/cascade`
+
+> ORM for managing databases
+
+## Skills
+
+- [aggregate-data](@warlock.js/cascade/aggregate-data/SKILL.md): Compute aggregates over a query — scalar `.count()` / `.sum(field)` / `.avg` / `.min` / `.max`, plus grouped rollups via the two-arg `.groupBy(fields, { alias: $agg.* })` with the `$agg` helpers and `.having(alias, op, value)` on computed aggregates. Triggers: `.count`, `.sum`, `.avg`, `.min`, `.max`, `.groupBy`, `.having`, `$agg`, `$agg.sum`, `$agg.count`; "monthly revenue report", "X per category", "group by status", "dashboard rollup"; typical import `import { Model, $agg } from "@warlock.js/cascade"`. Skip: row queries — `@warlock.js/cascade/query-data/SKILL.md`; cached aggregates — `@warlock.js/cache/use-cached-hof/SKILL.md`; competing tools raw SQL `GROUP BY`, `mongoose aggregate`, `prisma` `groupBy`.
+- [cascade-basics](@warlock.js/cascade/cascade-basics/SKILL.md): Start with @warlock.js/cascade ORM — model-first for MongoDB and Postgres, one schema (seal) does triple duty (type / validator / DB shape), model is the query entry point. Triggers: `Model`, `RegisterModel`, `connectToDatabase`, `Infer`, `v.object`; "which cascade skill do I need", "set up the ORM", "define my first model", "model-first ORM"; typical import `import { Model, RegisterModel } from "@warlock.js/cascade"`. Skip: schema vocabulary — `@warlock.js/seal/seal-basics/SKILL.md`; competing libs `mongoose`, `prisma`, `typeorm`, `drizzle`, `sequelize`, `mongodb` driver, `knex`.
+- [configure-delete-strategy](@warlock.js/cascade/configure-delete-strategy/SKILL.md): Pick the delete behavior — `permanent` (hard delete), `soft` (set `deletedAt`, keep the row), `trash` (move to a separate table). Configure via `static deleteStrategy` or `.destroy({ strategy })`; restore via static `Model.restore(id)` / `Model.restoreAll()`. Triggers: `static deleteStrategy`, `.destroy`, `Model.restore`, `Model.restoreAll`, `deletedAtColumn`, `trashTable`; "soft delete users", "restore a deleted record", "GDPR hard delete"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: lifecycle events — `@warlock.js/cascade/subscribe-to-model-events/SKILL.md`; competing libs `mongoose-delete`, `typeorm softRemove`, `sequelize` paranoid.
+- [define-model](@warlock.js/cascade/define-model/SKILL.md): Define a Cascade model — `@RegisterModel()`, class extends `Model<TSchema>`, `static table`, `static schema`, three update idioms (`.set` / `.merge` / `.save`), `.unset`, `.destroy`, `static toJsonColumns` / `resource` for output shaping. Triggers: `Model`, `RegisterModel`, `static schema`, `.set`, `.merge`, `.save`, `.unset`, `.destroy`, `toJsonColumns`, `resource`; "how do I define a model", "shape the JSON output", "remove a field"; typical import `import { Model, RegisterModel } from "@warlock.js/cascade"`. Skip: querying — `@warlock.js/cascade/query-data/SKILL.md`; relations — `@warlock.js/cascade/define-relations/SKILL.md`; competing libs `mongoose`, `prisma`, `typeorm` `@Entity`.
+- [define-relations](@warlock.js/cascade/define-relations/SKILL.md): Define and query relations — `@BelongsTo` / `@HasMany` / `@BelongsToMany`, `.with("relation")` eager loading, `.whereHas(relation, cb)` filter-by-related, `setRelation` on save, `.joinWith` for SQL joins, `loadRelation`, `lazy(() => Model)`. Triggers: `@BelongsTo`, `@HasMany`, `@BelongsToMany`, `.with`, `.whereHas`, `setRelation`, `.joinWith`, `lazy`; "define a relation", "avoid N+1", "eager load posts", "filter parents by child"; typical import `import { BelongsTo, HasMany, BelongsToMany } from "@warlock.js/cascade"`. Skip: model basics — `@warlock.js/cascade/define-model/SKILL.md`; competing libs `mongoose populate`, `prisma include`, `typeorm relations`.
+- [manage-data-sources](@warlock.js/cascade/manage-data-sources/SKILL.md): Configure multiple databases — register each via `connectToDatabase({ name, driver, database, isDefault })`, assign a model with `static dataSource = "name"`, route a migration with `dataSource` on the migration class, inspect via `dataSourceRegistry.get(name)` / `getAllDataSources()`. The first (or `isDefault: true`) source is the default. Triggers: `connectToDatabase`, `dataSourceRegistry`, `dataSourceRegistry.get`, `getAllDataSources`, `static dataSource`; "multi-database app", "per-tenant DB", "analytics on separate DB"; typical import `import { connectToDatabase, dataSourceRegistry } from "@warlock.js/cascade"`. Skip: per-source migrations — `@warlock.js/cascade/write-migration/SKILL.md`; transaction scope — `@warlock.js/cascade/manage-transactions/SKILL.md`; competing patterns `mongoose.createConnection`, `typeorm` `DataSource`, `prisma` multi-schema.
+- [manage-transactions](@warlock.js/cascade/manage-transactions/SKILL.md): Wrap multi-statement work in `transaction(async () => {...})` — rollback on throw, commit on resolve, optional `isolation` level (Postgres), per-`dataSource` scope. Postgres native; MongoDB requires replica set. Triggers: `transaction`, `isolation`, `SERIALIZABLE`, `READ COMMITTED`, nested savepoints; "wrap two writes atomically", "transfer balance between accounts", "rollback on error", "MongoDB replica set transactions"; typical import `import { transaction } from "@warlock.js/cascade"`. Skip: single-row atomic ops without a transaction — `@warlock.js/cascade/perform-atomic-ops/SKILL.md`; per-source scope — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing patterns `mongoose.startSession`, `pg` `BEGIN` manually, `prisma.$transaction`, `typeorm` `QueryRunner`.
+- [paginate-results](@warlock.js/cascade/paginate-results/SKILL.md): Paginate query results — `.paginate({page, limit, filter?})` for offset (returns `data` + `pagination` total/page/limit/pages), `.cursorPaginate({limit, cursor})` for very large datasets, `.chunk(size, callback)` for streaming. Triggers: `.paginate`, `.cursorPaginate`, `.chunk`, `nextCursor`, `hasMore`, `pagination.total`; "paginate the list", "infinite scroll / load more", "stream a large table", "page 2 of users"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: filter chain — `@warlock.js/cascade/query-data/SKILL.md`; eager loading on pages — `@warlock.js/cascade/define-relations/SKILL.md`; competing libs `mongoose-paginate-v2`, `prisma` cursor, `typeorm-pagination`.
+- [perform-atomic-ops](@warlock.js/cascade/perform-atomic-ops/SKILL.md): Avoid races on concurrent writes — `Model.increase(filter, field, n)` / `Model.decrease` for atomic counters, `Model.atomic(filter, ops)` for arbitrary mutations (`$set` / `$inc` / `$push` / `$pull`), `Model.createMany` / `Model.findAndUpdate` / `Model.delete` for bulk. Triggers: `Model.increase`, `Model.decrease`, `Model.atomic`, `Model.createMany`, `Model.findAndUpdate`, `Model.delete`, `$inc`, `$set`; "increment counter under concurrency", "bulk insert without N+1", "atomic update without loading"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: multi-row atomicity — `@warlock.js/cascade/manage-transactions/SKILL.md`; competing patterns `mongoose findOneAndUpdate`, `pg` `UPDATE ... SET x = x + 1`.
+- [query-data](@warlock.js/cascade/query-data/SKILL.md): Query records via the model — `.where(field, value)` / `.where(field, op, value)`, `.find(id)` / `.first` / `.all`, `.orderBy`, `.count` / `.exists`, plus `.whereIn` / `.whereBetween` / `.whereLike` / `.pluck` / `.firstOrFail` / scopes via `addScope`. Triggers: `.where`, `.find`, `.first`, `.firstOrFail`, `.all`, `.get`, `.orderBy`, `.exists`, `.whereIn`, `.whereBetween`, `addScope`; "filter by status", "find by id", "fetch active users", "check existence"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: pagination — `@warlock.js/cascade/paginate-results/SKILL.md`; aggregates — `@warlock.js/cascade/aggregate-data/SKILL.md`.
+- [run-cascade-cli](@warlock.js/cascade/run-cascade-cli/SKILL.md): Cascade's standalone `cascade` binary + the Operations API it wraps — `cascade migrate` / `migrate:list` / `migrate:rollback` / `migrate:export-sql`, and `runMigrations` / `rollbackMigrations` / `freshMigrate` / `exportMigrationsSQL` / `listExecutedMigrations` / `createDatabase` / `dropAllTables` / `migrationRunner`. Triggers: `cascade migrate`, `migrate:list`, `migrate:rollback`, `migrate:export-sql`, `runMigrations`, `rollbackMigrations`, `freshMigrate`, `exportMigrationsSQL`, `listExecutedMigrations`, `migrationRunner`; "run migrations in deploy/CI", "reset DB for tests", "programmatic migration", "foreign key constraint cannot be implemented", `CASCADE_PRIMARY_KEY`; typical import `import { runMigrations, migrationRunner } from "@warlock.js/cascade"`. Skip: writing migration files — `@warlock.js/cascade/write-migration/SKILL.md`; competing tools `knex migrate:latest`, `prisma migrate deploy`, `typeorm migration:run`.
+- [search-by-vector](@warlock.js/cascade/search-by-vector/SKILL.md): Vector similarity search via `.similarTo(column, embedding, alias?)` — adds a similarity `score` column and orders by vector distance so the index is used; cap results with `.limit()`. Postgres uses pgvector (IVFFlat index via `this.vectorIndex`); MongoDB needs Atlas. Schema: `this.vector(column, dimensions)` + `this.vectorIndex(column, { dimensions, similarity })`. Triggers: `.similarTo`, `this.vector`, `this.vectorIndex`, `.whereFullText`, pgvector; "semantic search", "RAG retrieval", "find similar articles", "hybrid vector + full-text"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: query basics — `@warlock.js/cascade/query-data/SKILL.md`; semantic cache — `@warlock.js/cache/use-cache-similarity/SKILL.md`; competing libs `pgvector` directly, `chromadb`, `pinecone`, `weaviate`, `qdrant`.
+- [subscribe-to-model-events](@warlock.js/cascade/subscribe-to-model-events/SKILL.md): 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.
+- [track-changes](@warlock.js/cascade/track-changes/SKILL.md): 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.
+- [write-migration](@warlock.js/cascade/write-migration/SKILL.md): Write a Cascade migration — the declarative `Migration.create(Model, { columns })` / `Migration.alter(Model, { ... })` factory is the primary form (column helpers `string` / `text` / `uuid` / `integer` imported from cascade, chained with `.notNullable()` / `.unique()` / `.references()`); the `extends Migration` class form is the imperative escape hatch. Run with the `cascade migrate` CLI; pin a source via `public dataSource`. Triggers: `Migration.create`, `Migration.alter`, `string()`, `text()`, `uuid()`, `.references`, `extends Migration`, `cascade migrate`; "write a migration", "create the users table", "add a column", "rollback the last batch"; typical import `import { Migration, text, uuid } from "@warlock.js/cascade"`. Skip: running migrations programmatically — `@warlock.js/cascade/run-cascade-cli/SKILL.md`; per-source migrations — `@warlock.js/cascade/manage-data-sources/SKILL.md`; competing tools `knex migrate`, `prisma migrate`, `typeorm migration`.

package/package.json

@@ -1,53 +1,62 @@
 {
-    "name": "@warlock.js/cascade",
-    "version": "4.0.171",
-    "description": "ORM for managing databases",
-    "main": "./esm/index.js",
-    "dependencies": {
-        "@mongez/copper": "^1.0.1",
-        "@mongez/events": "^2.1.0",
-        "@mongez/reinforcements": "^2.3.17",
-        "@mongez/supportive-is": "^2.0.0",
-        "@warlock.js/context": "4.0.171",
-        "@warlock.js/logger": "4.0.171",
-        "@warlock.js/seal": "4.0.171"
+  "name": "@warlock.js/cascade",
+  "description": "ORM for managing databases",
+  "keywords": [
+    "mongodb",
+    "postgres",
+    "node",
+    "database",
+    "orm",
+    "mongodb-orm",
+    "mongodb-odm",
+    "mongodb-orm-node",
+    "entity",
+    "model",
+    "aggregate",
+    "aggregate-framework"
+  ],
+  "author": "hassanzohdy",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/warlockjs/cascade"
+  },
+  "dependencies": {
+    "@mongez/copper": "^2.1.2",
+    "@mongez/dotenv": "^1.2.4",
+    "@mongez/events": "^2.2.6",
+    "@mongez/reinforcements": "^3.2.0",
+    "@mongez/supportive-is": "^2.1.3",
+    "@warlock.js/context": "*",
+    "@warlock.js/logger": "*",
+    "@warlock.js/seal": "*",
+    "citty": "^0.2.2",
+    "fast-glob": "^3.3.3"
+  },
+  "peerDependencies": {
+    "mongodb": "^5.7.0 || ^6.0.0 || ^7.0.0",
+    "pg": "^8.16.3"
+  },
+  "bin": {
+    "cascade": "bin/cascade.js"
+  },
+  "version": "4.1.1",
+  "type": "module",
+  "main": "./esm/index.mjs",
+  "module": "./esm/index.mjs",
+  "types": "./esm/index.d.mts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./esm/index.d.mts",
+        "default": "./esm/index.mjs"
+      }
     },
-    "scripts": {
-        "update": "npx ncu -u",
-        "fix:test": "eslint --fix -c ./.eslintrc.json ./tests",
-        "format:test": "prettier --write ./tests/**/*.{js,jsx,ts,tsx,css,md,json} --config ./.prettierrc.json",
-        "fix": "eslint --fix -c ./.eslintrc.json ./src",
-        "format": "prettier --write ./src/**/*.{js,jsx,ts,tsx,css,md,json} --config ./.prettierrc.json",
-        "test": "jest tests"
-    },
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/warlockjs/cascade"
-    },
-    "devDependencies": {
-        "mongodb": "^7.0.0",
-        "typescript": "^5.1.6"
-    },
-    "peerDependencies": {
-        "mongodb": "^5.7.0 || ^6.0.0 || ^7.0.0",
-        "pg": "^8.16.3"
-    },
-    "keywords": [
-        "mongodb",
-        "node",
-        "database",
-        "orm",
-        "mongodb-orm",
-        "mongodb-odm",
-        "mongodb-orm-node",
-        "entity",
-        "model",
-        "aggregate",
-        "aggregate-framework"
-    ],
-    "author": "hassanzohdy",
-    "license": "MIT",
-    "module": "./esm/index.js",
-    "typings": "./esm/index.d.ts",
-    "type": "module"
-}
+    "./cli": {
+      "import": {
+        "types": "./esm/cli.d.mts",
+        "default": "./esm/cli.mjs"
+      }
+    }
+  }
+}

package/skills/README.md

@@ -0,0 +1,65 @@
+# `@warlock.js/cascade` — skills index
+
+Per-task skills. All cross-references use the form `@warlock.js/<pkg>/<skill>/SKILL.md`.
+
+## Skills
+
+### [`aggregate-data/`](./aggregate-data/SKILL.md)
+
+Compute aggregates over a query — `.count()`, `.sum(field)`, `.avg`, `.min`, `.max`, plus the two-arg `.groupBy(fields, { alias: $agg.* })` + `.having` for group-level rollups. Load when building reports, dashboards, 'X per category' rollups, or any query returning numbers rather than rows.
+
+### [`cascade-basics/`](./cascade-basics/SKILL.md)
+
+Start with @warlock.js/cascade ORM — model-first for MongoDB and Postgres, one schema (seal) does triple duty (type / validator / DB shape), model is the query entry point. Load when importing @warlock.js/cascade, wiring connectToDatabase, defining the first model, or choosing which cascade skill to load.
+
+### [`configure-delete-strategy/`](./configure-delete-strategy/SKILL.md)
+
+Pick the delete behavior — `permanent` (hard delete), `soft` (set deletedAt, keep the row), `trash` (move to a separate table). Configure per-model via `static deleteStrategy` or pass `.destroy({ strategy })` per call; restore via static `Model.restore(id)` / `Model.restoreAll()`. Soft-deleted rows are NOT auto-hidden — add a `notDeleted` global scope yourself. Load when records should be reversibly deletable or implementing GDPR hard delete.
+
+### [`define-model/`](./define-model/SKILL.md)
+
+Define a Cascade model — @RegisterModel() decorator, class extends Model<TSchema>, static table, static schema, three update idioms (.set / .merge / .save), .unset, .destroy, static toJsonColumns / resource for output shaping. Load when creating a model file, adding accessors, or shaping serialized output.
+
+### [`define-relations/`](./define-relations/SKILL.md)
+
+Define and query relations — @BelongsTo('Model') / @HasMany('Model') / @BelongsToMany('Model', { pivot, localKey, foreignKey }), .with('relation') eager loading, .whereHas(relation, cb) filter-by-related, setRelation on save, .joinWith for SQL joins, .load(relation) for lazy loading. Load when two models reference each other, avoiding N+1, or filtering parents by child conditions.
+
+### [`manage-data-sources/`](./manage-data-sources/SKILL.md)
+
+Configure multiple databases — register each via `connectToDatabase({ name, driver, database, isDefault })`, assign a model with `static dataSource = 'name'`, pin a migration with `public dataSource`, inspect via `dataSourceRegistry.get(name)` / `getAllDataSources()`. Load when the app talks to more than one database (reporting replica, analytics DB, per-tenant DBs).
+
+### [`manage-transactions/`](./manage-transactions/SKILL.md)
+
+Wrap multi-statement work in transaction(async () => {...}) — rollback on throw or `ctx.rollback()`, commit on resolve, `isolationLevel` option (Postgres). Postgres native, MongoDB requires replica set; not nestable. Load when two or more writes must succeed or fail together (creating parent + children, transferring balances, multi-step state machines).
+
+### [`paginate-results/`](./paginate-results/SKILL.md)
+
+Paginate query results — `.paginate({ page, limit })` for offset (returns `data` + `pagination`), `.cursorPaginate({ limit, cursor })` for very large datasets (cursor fields under `pagination`), `.chunk(size, callback)` for streaming. Load when listing records for a UI, fetching a slice for an API, or processing a large table in batches.
+
+### [`perform-atomic-ops/`](./perform-atomic-ops/SKILL.md)
+
+Avoid races on concurrent writes — Model.increase(filter, field, n) / Model.decrease for atomic counters, Model.atomic(filter, ops) for arbitrary atomic mutations, Model.createMany / Model.findAndUpdate / Model.delete for bulk. Load when incrementing counters under concurrency, bulk ops without N+1, or single-document atomic mutations without a full transaction.
+
+### [`query-data/`](./query-data/SKILL.md)
+
+Query records via the model — .where(field, value) / .where(field, op, value), .find(id) / .first(filter?) / .all(filter?), .count / .exists, plus the broader query-builder vocabulary (.orderBy / .whereIn / .whereBetween / .whereLike / .pluck / .firstOrFail / scopes) via .query() or chained off .where(). Load when filtering, fetching by ID, getting a single match, or ordering.
+
+### [`run-cascade-cli/`](./run-cascade-cli/SKILL.md)
+
+Cascade's standalone CLI binary + programmatic Operations API — cascade migrate / migrate:list / migrate:rollback / migrate:export-sql, plus runMigrations / rollbackMigrations / freshMigrate / exportMigrationsSQL / listExecutedMigrations / migrationRunner functions. Load when applying migrations during deploy, resetting DB for test setup, or programmatic migration ops from a custom script.
+
+### [`search-by-vector/`](./search-by-vector/SKILL.md)
+
+Vector similarity search via `.similarTo(column, embedding, alias?)` — adds a `score` column, orders by distance for index usage, cap with `.limit()`. Postgres uses pgvector (IVFFlat index via `this.vectorIndex`); MongoDB uses Atlas. Load when building semantic search, RAG retrieval against documents, hybrid (vector + full-text) search, or 'find records most similar to this vector'.
+
+### [`subscribe-to-model-events/`](./subscribe-to-model-events/SKILL.md)
+
+Hook into model lifecycle events — `saving` / `saved`, `creating` / `created`, `updating` / `updated`, `validating` / `validated`, `deleting` / `deleted`, `restoring` / `restored`, `fetching` / `fetched`. The gerund form is the "before" hook (no `beforeSave` alias). Per-model `Model.on` or global. Load when wiring an audit log, sending notifications on changes, or denormalizing into a search index.
+
+### [`track-changes/`](./track-changes/SKILL.md)
+
+Inspect a model's pending changes — `hasChanges()`, `isDirty(column)`, `getDirtyColumns()` (changed field names), `getDirtyColumnsWithValues()` (old + new per field), `getRemovedColumns()`. Load when implementing audit logs, conditionally running expensive logic only if a field changed, or building a change diff.
+
+### [`write-migration/`](./write-migration/SKILL.md)
+
+Write a Cascade migration — a class `extends Migration` with `public table`, `up()` / `down()`, and fluent schema builders on `this` (`createTable`, `id`, `string`, `timestamps`, `references`, `index`). Run with `cascade migrate`. Load when creating or altering a table, indexing a column, dropping data, or wiring a new model.

package/skills/aggregate-data/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: aggregate-data
+description: 'Compute aggregates over a query — scalar `.count()` / `.sum(field)` / `.avg` / `.min` / `.max`, plus grouped rollups via the two-arg `.groupBy(fields, { alias: $agg.* })` with the `$agg` helpers and `.having(alias, op, value)` on computed aggregates. Triggers: `.count`, `.sum`, `.avg`, `.min`, `.max`, `.groupBy`, `.having`, `$agg`, `$agg.sum`, `$agg.count`; "monthly revenue report", "X per category", "group by status", "dashboard rollup"; typical import `import { Model, $agg } from "@warlock.js/cascade"`. Skip: row queries — `@warlock.js/cascade/query-data/SKILL.md`; cached aggregates — `@warlock.js/cache/use-cached-hof/SKILL.md`; competing tools raw SQL `GROUP BY`, `mongoose aggregate`, `prisma` `groupBy`.'
+---
+
+# Use aggregates and groupBy
+
+Cascade's query builder isn't only for finding records — it crunches numbers too. The same calls run on MongoDB and Postgres.
+
+## Scalar aggregates
+
+```ts
+const total      = await Order.count();                  // count is static on the model
+const revenue    = await Order.query().sum("total");
+const avgTicket  = await Order.query().avg("total");
+const cheapest   = await Order.query().min("total");
+const priciest   = await Order.query().max("total");
+
+// Filtered
+const monthRevenue = await Order.query()
+  .whereDateAfter("created_at", startOfMonth)
+  .sum("total");
+```
+
+Each returns a single number (`Promise<number>`). Only `count` is a static shortcut on the model; `sum` / `avg` / `min` / `max` (and the date helpers) are query-builder methods — reach them via `Order.query()` or chain off `Order.where(...)`. Date filters take a single date: `whereDate(field, value)` (exact day, time ignored), `whereDateAfter` / `whereDateBefore` (one-sided), `whereDateBetween(field, [a, b])` (range) — there is no 3-arg `whereDate(field, op, value)`. By Cascade convention the scalar terminators return **`0` on zero rows — not `null`** — so you can use the result directly without a null guard.
+
+## Grouped rollups — two-arg `groupBy(fields, aggregates)`
+
+To compute aggregates *per group*, pass a second argument to `groupBy`: an object mapping output aliases to aggregate expressions. Build the expressions with the `$agg` helpers:
+
+```ts
+import { $agg } from "@warlock.js/cascade";
+
+const stats = await Order.query()
+  .groupBy("category", {
+    total: $agg.sum("amount"),
+    orders: $agg.count(),
+    avg: $agg.avg("amount"),
+  })
+  .get();
+// each row: { category, total, orders, avg }
+```
+
+`fields` is a string or string array (`groupBy(["status", "country"], {...})` groups by each combination). Single-arg `groupBy("category")` / `groupBy(["a","b"])` groups **without** computing aggregates.
+
+### `$agg` helpers — five cross-driver, four MongoDB-only
+
+Cross-driver (identical call on MongoDB **and** Postgres):
+
+- `$agg.count()` · `$agg.sum(field)` · `$agg.avg(field)` · `$agg.min(field)` · `$agg.max(field)`
+
+MongoDB-only — on Postgres these **throw at the `.groupBy()` call** with an actionable message (there is no honest single-scalar `GROUP BY` equivalent):
+
+- `$agg.distinct(field)` · `$agg.floor(field)` · `$agg.first(field)` · `$agg.last(field)`
+
+If you need those shapes on Postgres, drop to `selectRaw` / `havingRaw` with explicit SQL (e.g. `array_agg(DISTINCT …)`, a window function).
+
+### Driver-specific escape hatch
+
+When `$agg.*` can't express it, pass a raw expression in the same slot:
+
+```ts
+.groupBy("category", { total: "SUM(amount)" })          // Postgres
+.groupBy("category", { total: { $sum: "$amount" } })    // MongoDB
+```
+
+Raw strings pass through verbatim. A MongoDB operator object passed on Postgres throws ("not portable to SQL") — keep raw expressions driver-correct.
+
+## `.having(...)` — filter groups by a computed aggregate
+
+`.where()` filters rows *before* grouping (cheap, uses indexes). `.having()` filters *after* aggregation, by the alias you defined:
+
+```ts
+const big = await Order.query()
+  .groupBy("category", { total: $agg.sum("amount") })
+  .having("total", ">", 1000)
+  .get();
+```
+
+Works identically on both drivers. (Internally Postgres can't reference a SELECT alias in `HAVING`, so Cascade substitutes the underlying expression for you.) `having` accepts the same shapes as `where`: `having("total", 1000)`, `having("total", ">", 1000)`, `having({ total: 1000, orders: 5 })`. A `having()` on a **grouped column** (not an aggregate alias) is left as a plain column filter.
+
+## OrderBy on aggregates
+
+```ts
+await Order.query()
+  .groupBy("category", { revenue: $agg.sum("amount") })
+  .orderBy("revenue", "desc")
+  .get();
+```
+
+The `orderBy` reference matches the alias from the aggregates object.
+
+## Gotchas
+
+- **`where` vs `having`.** Row filters go in `.where()` (before grouping, index-friendly); aggregate filters go in `.having()`.
+- **Empty sets.** Scalar terminators return `0` on zero rows (above). For *grouped* reports, a group with no rows simply doesn't appear — a report over an empty range returns `[]`, not a row of zeros.
+- **Don't `.all()` then `array.reduce`.** Always push aggregates to the database.
+
+## See also
+
+- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — the broader query vocabulary
+- [`@warlock.js/cache/use-cached-hof/SKILL.md`](@warlock.js/cache/use-cached-hof/SKILL.md) — caching expensive aggregate results

package/skills/cascade-basics/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: cascade-basics
+description: 'Start with @warlock.js/cascade ORM — model-first for MongoDB and Postgres, one schema (seal) does triple duty (type / validator / DB shape), model is the query entry point. Triggers: `Model`, `RegisterModel`, `connectToDatabase`, `Infer`, `v.object`; "which cascade skill do I need", "set up the ORM", "define my first model", "model-first ORM"; typical import `import { Model, RegisterModel } from "@warlock.js/cascade"`. Skip: schema vocabulary — `@warlock.js/seal/seal-basics/SKILL.md`; competing libs `mongoose`, `prisma`, `typeorm`, `drizzle`, `sequelize`, `mongodb` driver, `knex`.'
+---
+
+# Cascade basics
+
+Model-first TypeScript ORM for MongoDB and Postgres. Query straight off the model — `User.where(...)`, `User.find(id)`, `User.paginate(...)`. One schema (via `@warlock.js/seal`) does triple duty: TS type via `Infer<>`, runtime validator on save, DB shape via the migration.
+
+> This skill is the cascade **map** — read it first, then load the specific skill for the task.
+
+## Install
+
+```bash
+yarn add @warlock.js/cascade @warlock.js/seal
+```
+
+## Foundations
+
+The 10 things that are true in every cascade use:
+
+1. **The model is the query entry point.** `User.where(...)`, `User.find(id)`, `User.paginate(...)`. No `db.users`, no separate client, no repository layer.
+2. **One schema does triple duty.** `userSchema` via `v.object({...})` is your TS type (`Infer<typeof userSchema>`), your runtime validator on save, and the shape your migration writes against. Defined via [`@warlock.js/seal/seal-basics/SKILL.md`](@warlock.js/seal/seal-basics/SKILL.md).
+3. **`@RegisterModel()` puts the model in the global registry.** Other models look it up by name for relations (`@BelongsTo("User")` or `@BelongsTo(lazy(() => User))`).
+4. **Two drivers ship in-box: MongoDB and Postgres.** Same query API across both. Switch via config; the call sites stay identical.
+5. **Migrations are required.** `cascade migrate` runs schema changes; the model class doesn't auto-create tables. See [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md).
+6. **`.create()` validates against the schema before persisting.** Defaults (`v.string().default(...)`) fire here. Validation errors throw — see [`@warlock.js/seal/handle-seal-errors/SKILL.md`](@warlock.js/seal/handle-seal-errors/SKILL.md).
+7. **Three update idioms — pick by shape.** `.set(k, v).save()` for 1–2 fields, `.merge(data).save()` for object payloads, `.save()` after spread mutations. See [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md).
+8. **`.destroy()` runs the configured delete strategy** (`permanent` / `soft` / `trash`). See [`@warlock.js/cascade/configure-delete-strategy/SKILL.md`](@warlock.js/cascade/configure-delete-strategy/SKILL.md).
+9. **Lifecycle events fire on every meaningful moment** — `saving` / `saved`, `creating` / `created`, `deleting` / `deleted`. Hook on the model class. See [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md).
+10. **Transactions are first-class.** `transaction(async () => { ... })` wraps a unit; rollback on throw, commit on resolve. See [`@warlock.js/cascade/manage-transactions/SKILL.md`](@warlock.js/cascade/manage-transactions/SKILL.md).
+
+## Minimal example — model, write, read
+
+```ts
+import { v, type Infer } from "@warlock.js/seal";
+import { Model, RegisterModel } from "@warlock.js/cascade";
+
+const userSchema = v.object({
+  name: v.string(),
+  email: v.string().email(),
+  status: v.literal("active", "inactive").default("active"),
+});
+
+type UserSchema = Infer<typeof userSchema>;
+
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+}
+
+// Write
+const user = await User.create({ name: "Ada Lovelace", email: "ada@example.com" });
+user.id;                  // generated ID — direct property
+user.get("status");        // "active" — default fired
+
+// Read
+const found = await User.find(user.id);
+found?.get("email");       // "ada@example.com"
+
+// Filter
+const active = await User.where("status", "active").get();
+const page = await User.paginate({ page: 1, limit: 20 });
+```
+
+## Pick a skill
+
+| If the task is about… | Load |
+| --- | --- |
+| Defining a model class — schema, decorators, `Model<TSchema>`, accessors | [`@warlock.js/cascade/define-model/SKILL.md`](@warlock.js/cascade/define-model/SKILL.md) |
+| Querying — `.where`, `.find`, `.first`, `.all`, `.count`, `.exists`, ordering | [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) |
+| Pagination — `.paginate`, `cursorPaginate`, `chunk` | [`@warlock.js/cascade/paginate-results/SKILL.md`](@warlock.js/cascade/paginate-results/SKILL.md) |
+| Relations — `belongsTo` / `hasMany` / `belongsToMany`, eager loading | [`@warlock.js/cascade/define-relations/SKILL.md`](@warlock.js/cascade/define-relations/SKILL.md) |
+| Migrations — `migration` definition, `up`/`down`, CLI | [`@warlock.js/cascade/write-migration/SKILL.md`](@warlock.js/cascade/write-migration/SKILL.md) |
+| Transactions — `transaction(fn)`, rollback, isolation | [`@warlock.js/cascade/manage-transactions/SKILL.md`](@warlock.js/cascade/manage-transactions/SKILL.md) |
+| Dirty tracking — `hasChanges`, `isDirty`, `getDirtyColumns`, `getDirtyColumnsWithValues` | [`@warlock.js/cascade/track-changes/SKILL.md`](@warlock.js/cascade/track-changes/SKILL.md) |
+| Lifecycle hooks — `saving`, `saved`, `deleting`, `deleted` | [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md) |
+| Soft / hard / trash deletes + restore | [`@warlock.js/cascade/configure-delete-strategy/SKILL.md`](@warlock.js/cascade/configure-delete-strategy/SKILL.md) |
+| Atomic ops — `Model.increase`, `decrease`, `atomic`, `Model.delete(filter)` | [`@warlock.js/cascade/perform-atomic-ops/SKILL.md`](@warlock.js/cascade/perform-atomic-ops/SKILL.md) |
+| Aggregates — `.sum`, `.avg`, `.count`, `.groupBy`, `.having` | [`@warlock.js/cascade/aggregate-data/SKILL.md`](@warlock.js/cascade/aggregate-data/SKILL.md) |
+| Vector search — `similarTo`, pgvector / Atlas vector index | [`@warlock.js/cascade/search-by-vector/SKILL.md`](@warlock.js/cascade/search-by-vector/SKILL.md) |
+| Multiple databases — `connectToDatabase`, per-model `static dataSource` | [`@warlock.js/cascade/manage-data-sources/SKILL.md`](@warlock.js/cascade/manage-data-sources/SKILL.md) |
+| CLI + Operations API — `cascade migrate`, `migrate:rollback`, programmatic | [`@warlock.js/cascade/run-cascade-cli/SKILL.md`](@warlock.js/cascade/run-cascade-cli/SKILL.md) |
+
+## Things NOT to do
+
+- Don't call `new User()` directly to create a record. Use `User.create({...})` — it runs validation, generates IDs, fires events.
+- Don't `.set()` a relation slot (e.g. `user.set("contact", contactModel)`). Use `setRelation("contact", contactModel)` — relations have their own slot semantics.
+- Don't forget `await` on writes. Without it, the mutation lives on the instance and never reaches the DB.
+- Don't reach for `.count() > 0` to test existence. Use `.exists()` / `.notExists()` — short-circuits, doesn't hydrate.
+- Don't return the raw model from an HTTP handler. `JSON.stringify(user)` returns the entire row; configure `static toJsonColumns` or `static resource` to shape the public output.
+- Don't auto-run migrations from app code. They're a deploy step; run via `cascade migrate` or the Operations API.

package/skills/configure-delete-strategy/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: configure-delete-strategy
+description: 'Pick the delete behavior — `permanent` (hard delete), `soft` (set `deletedAt`, keep the row), `trash` (move to a separate table). Configure via `static deleteStrategy` or `.destroy({ strategy })`; restore via static `Model.restore(id)` / `Model.restoreAll()`. Triggers: `static deleteStrategy`, `.destroy`, `Model.restore`, `Model.restoreAll`, `deletedAtColumn`, `trashTable`; "soft delete users", "restore a deleted record", "GDPR hard delete"; typical import `import { Model } from "@warlock.js/cascade"`. Skip: lifecycle events — `@warlock.js/cascade/subscribe-to-model-events/SKILL.md`; competing libs `mongoose-delete`, `typeorm softRemove`, `sequelize` paranoid.'
+---
+
+# Use delete strategies
+
+`destroy()` does more than `DELETE FROM table`. Cascade supports three strategies that change what happens to the record. Your data source's `defaultDeleteStrategy` applies unless you override per-model or per-call; with nothing configured the fallback is `permanent`.
+
+## The three strategies
+
+`DeleteStrategy` is `"permanent" | "soft" | "trash"`.
+
+| Strategy | Behavior | Reversible? |
+| --- | --- | --- |
+| `permanent` | DELETE the row / document (the default fallback) | No |
+| `soft` | Set the `deletedAt` column; the row stays in the table | Yes — via `Model.restore(id)` |
+| `trash` | Move the record to a separate table / collection, then delete the original | Yes — via `Model.restore(id)` |
+
+## Set the default per-model
+
+```ts
+import { Model, RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+  public static deleteStrategy = "soft" as const; // every destroy() is soft unless overridden
+  public static deletedAtColumn = "deletedAt"; // default; set false to disable the column
+}
+```
+
+## Override per-call
+
+```ts
+await user.destroy();                            // uses the model's strategy
+await user.destroy({ strategy: "permanent" });   // GDPR-compliant hard delete
+await user.destroy({ strategy: "trash" });       // move to the trash table
+```
+
+Resolution order: `destroy({ strategy })` → `static deleteStrategy` → data source `defaultDeleteStrategy` → `"permanent"`.
+
+## Restoring — static, by id
+
+Restore is a **static** operation keyed by the record's id. It auto-detects whether the record was soft-deleted or trashed:
+
+```ts
+const user = await User.restore(123);            // clears deletedAt or pulls from trash; fires "restored"
+const user2 = await User.restore(123, { onIdConflict: "fail" });
+
+await User.restoreAll();                          // restore every deleted record for this model
+```
+
+There is no instance `user.restore()` — call `User.restore(id)`. `restoreAll(options?)` restores all soft-deleted (or all trashed) records for the model's table.
+
+## Trash strategy — a separate store
+
+```ts
+await user.destroy({ strategy: "trash" }); // moved to the model's trash table, original deleted
+
+await User.restore(user.id); // pull back out of the trash table
+```
+
+The trash table name resolves as: `static trashTable` on the model → data source `defaultTrashTable` → the `{table}Trash` pattern (e.g. `usersTrash`). Useful when soft-delete clutter would bloat the main table.
+
+## Querying soft-deleted records — you filter, Cascade doesn't
+
+**Important:** Cascade does **not** auto-hide soft-deleted rows. A plain `User.all()` returns deleted rows too, because the query builder has no built-in `deletedAt` filter. If you want the common "active records only" default, register a global scope yourself:
+
+```ts
+@RegisterModel()
+export class User extends Model<UserSchema> {
+  public static table = "users";
+  public static schema = userSchema;
+  public static deleteStrategy = "soft" as const;
+
+  static {
+    // hide soft-deleted rows from every query by default
+    this.addGlobalScope("notDeleted", (query) => {
+      query.whereNull("deletedAt");
+    });
+  }
+}
+```
+
+With that scope in place:
+
+```ts
+await User.all();                                          // active only (scope applied)
+await User.query().withoutGlobalScope("notDeleted").get(); // active + soft-deleted
+await User.query().withoutGlobalScope("notDeleted").whereNotNull("deletedAt").get(); // only deleted
+```
+
+`withoutGlobalScope("notDeleted")` bypasses the filter for one query; `withoutGlobalScopes()` drops all of them. See [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) for scopes.
+
+## Lifecycle hooks fire on all strategies
+
+The delete events are `deleting` / `deleted` (not `destroying` / `destroyed`):
+
+```ts
+User.on("deleting", async (user) => {
+  /* about to delete, any strategy */
+});
+User.on("deleted", async (user) => {
+  /* delete completed; context carries the strategy + trashRecord for trash */
+});
+User.on("restored", async (user) => {
+  /* soft-delete or trash restoration completed */
+});
+```
+
+See [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md).
+
+## Things NOT to do
+
+- Don't switch a model to `soft` without a migration adding the `deletedAt` column. The strategy writes to it.
+- Don't assume soft-deleted rows are hidden automatically — they're not. Add a `notDeleted` global scope (above) or filter `whereNull("deletedAt")` explicitly.
+- Don't call `user.restore()` — restore is static: `User.restore(id)` / `User.restoreAll()`.
+- Don't expect `restore` to undo a `permanent` delete. Hard deletes are gone.
+- Don't use soft delete for GDPR right-to-be-forgotten data. The record stays in the DB; you need `permanent` (plus backup cleanup).
+
+## See also
+
+- [`@warlock.js/cascade/subscribe-to-model-events/SKILL.md`](@warlock.js/cascade/subscribe-to-model-events/SKILL.md) — `deleting` / `deleted` / `restored` events
+- [`@warlock.js/cascade/query-data/SKILL.md`](@warlock.js/cascade/query-data/SKILL.md) — global scopes and `withoutGlobalScope` for surfacing deleted rows