@warlock.js/cascade 5.34.0 → 5.34.2

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@warlock.js/cascade` are documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). `@warlock.js/*` packages are released in lockstep — every package shares the same version number, so a version below may list only the changes that affected this package.
 
+## 5.34.2 - 2026-10-19
+
+### Fixed
+
+- Remove the redundant loose skill catalog and include package orientation in generated LLM projections.
+
 ## 5.34.0 - 2026-10-19
 
 ### Removed

package/llms-full.txt

@@ -4,6 +4,36 @@
 
 > Generated artifact. Concatenates every SKILL.md and reference file under `@warlock.js/cascade/skills/`. Re-run `node scripts/generate-llms.mjs` after any change.
 
+## Package orientation
+
+---
+description: "Model-first ORM for MongoDB and Postgres. Exports `Model`, `RegisterModel`, `Migration`, `defineModel`, `BelongsTo`, `HasMany`, `transaction`, `DataSource`, `dataSourceRegistry`, `connectToDatabase`, `runMigrations`. Use for: define a model, add a column or collection, write or alter a migration, query or filter records, paginate, aggregate or group, add a relation, run a transaction, soft delete, track changes, react to save or delete events, vector search. Not this package: request validation and schemas → @warlock.js/seal; routes, controllers, repositories → @warlock.js/core."
+---
+
+# @warlock.js/cascade
+
+Cascade is the data layer. The model is the query entry point (`User.find(id)`, `User.paginate(...)`); one seal schema gives the TypeScript type, the save-time validation, and the shape migrations write against. MongoDB and Postgres drivers ship with the same query API. Server-only.
+
+## The 80% path
+
+1. Read `cascade-basics.md` first: it is the map and the ten foundations.
+2. Define the model and register it (`define-model.md`), then relations (`define-relations.md`).
+3. Write the migration; models never create tables or collections on their own (`write-migration.md`, `alter-migration.md`, run with `run-cascade-cli.md`).
+4. Query, paginate, aggregate (`query-data.md`, `paginate-results.md`, `aggregate-data.md`, `perform-atomic-ops.md`).
+5. Wrap multi-step writes in a transaction (`manage-transactions.md`); pick a delete strategy (`configure-delete-strategy.md`).
+6. Connect and manage drivers (`manage-data-sources.md`); hook lifecycle and diffs (`subscribe-to-model-events.md`, `track-changes.md`); embeddings via `search-by-vector.md`.
+
+## Conventions and pitfalls
+
+- `pg` and `mongodb` are optional peers; install only the driver you use.
+- `.create()` validates against the schema, applies defaults, and throws on failure.
+- Pick an update idiom by shape: `.set(k, v).save()` for one or two fields, `.merge(data).save()` for payloads.
+- `.destroy()` follows the configured strategy (permanent, soft, or trash), not always a hard delete.
+- Relations refer to models by registered name, so `@RegisterModel()` must run first.
+- Run code needing a live connection through `onceConnected`, not at import time.
+- Undefined `where` values and unsafe filters throw on purpose; sanitize user-supplied filters.
+
+
 ## aggregate-data  `@warlock.js/cascade/aggregate-data/SKILL.md`
 
 ---

package/llms.txt

@@ -6,6 +6,7 @@
 
 ## Skills
 
+- [Package orientation](@warlock.js/cascade/skills/index.md): Model-first ORM for MongoDB and Postgres. Exports `Model`, `RegisterModel`, `Migration`, `defineModel`, `BelongsTo`, `HasMany`, `transaction`, `DataSource`, `dataSourceRegistry`, `connectToDatabase`, `runMigrations`. Use for: define a model, add a column or collection, write or alter a migration, query or filter records, paginate, aggregate or group, add a relation, run a transaction, soft delete, track changes, react to save or delete events, vector search. Not this package: request validation and schemas → @warlock.js/seal; routes, controllers, repositories → @warlock.js/core.
 - [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.* })`, portable date-bucketing via `.groupByDate(col, unit, aggregates?)`, the `$agg` helpers (including expression-aware `$agg.sum($expr.mul("price","quantity"))` / `$agg.sumRaw`), and `.having(alias, op, value)` on computed aggregates, plus MongoDB pipeline stages `.unwind(field, options?)` / `.addFields(fields)` / pipeline-form `join()` (`UnsupportedQueryOperationError` on Postgres). Triggers: `.unwind`, `.addFields`, `.joinRaw`, `.raw`, `$unwind`, `$lookup`, `.count`, `.sum`, `.avg`, `.min`, `.max`, `.groupBy`, `.groupByDate`, `.having`, `$agg`, `$agg.sum`, `$agg.sumRaw`, `$agg.count`, `$expr`, `$expr.mul`, `$expr.col`, `$expr.lit`; "monthly revenue report", "revenue per month", "X per category", "group by status", "sum price times quantity", "dashboard rollup"; typical import `import { Model, $agg, $expr } from "@warlock.js/cascade"`. Skip: row queries — the `query-data` topic; cached aggregates — the `use-cached-hof` topic of the `warlock-js-cache` skill; competing tools raw SQL `GROUP BY`, `mongoose aggregate`, `prisma` `groupBy`.
 - [alter-migration](@warlock.js/cascade/alter-migration/SKILL.md): Evolve an existing table with `Migration.alter(Model, schema, options?)` — add/drop/rename/modify columns; add/drop regular, unique, expression, full-text, geo, vector, and TTL indexes; add/drop foreign keys and CHECK constraints; write rollbacks with class-form methods in `down()`. Triggers: "alter a table", "add a column to existing table", "drop a column", "rename a column", "add an index", "drop a unique constraint", "change a column type", `Migration.alter`, `dropUnique`, `addIndex`, `addForeign`. Skip: creating a brand-new table — the `write-migration` topic.
 - [cascade-basics](@warlock.js/cascade/cascade-basics/SKILL.md): Start here for @warlock.js/cascade models, data sources, migrations, and query workflows.

package/package.json

@@ -13,10 +13,10 @@
     "@mongez/events": "^2.2.8",
     "@mongez/reinforcements": "^4.0.2",
     "@mongez/supportive-is": "^3.0.0",
-    "@warlock.js/context": "5.34.0",
-    "@warlock.js/logger": "5.34.0",
-    "@warlock.js/scheduler": "5.34.0",
-    "@warlock.js/seal": "5.34.0",
+    "@warlock.js/context": "5.34.2",
+    "@warlock.js/logger": "5.34.2",
+    "@warlock.js/scheduler": "5.34.2",
+    "@warlock.js/seal": "5.34.2",
     "citty": "^0.2.2",
     "fast-glob": "^3.3.3"
   },
@@ -53,7 +53,7 @@
   ],
   "author": "hassanzohdy",
   "license": "MIT",
-  "version": "5.34.0",
+  "version": "5.34.2",
   "main": "./cjs/index.cjs",
   "module": "./esm/index.mjs",
   "types": "./esm/index.d.mts",

package/skills/README.md

@@ -1,69 +0,0 @@
-# `@warlock.js/cascade` — skills index
-
-Per-task skills. Cross-references name the topic, for example "the `define-model` topic"; the other package's topics are named with the `warlock-js-<pkg>` skill that holds them.
-
-## Skills
-
-### `alter-migration.md`
-
-Evolve an existing table with `Migration.alter(Model, schema, options?)` — add/drop/rename/modify columns; add/drop regular, unique, expression, full-text, geo, vector, and TTL indexes; add/drop foreign keys and CHECK constraints; write rollbacks with class-form methods in `down()`. Load when changing an existing table — adding columns, swapping unique→index, wiring new foreign keys, or any DDL that's not creating a brand-new table.
-
-### `aggregate-data.md`
-
-Compute aggregates over a query — `.count()`, `.sum(field)`, `.avg`, `.min`, `.max`, the two-arg `.groupBy(fields, { alias: $agg.* })` + `.having`, portable date-bucketing via `.groupByDate(col, unit, aggregates?)`, and expression-aware `$agg.sum(mul("price","quantity"))` / `$agg.sumRaw` for group-level rollups. Load when building reports, dashboards, 'X per category' rollups, time-series ('revenue per month'), or any query returning numbers rather than rows.
-
-### `cascade-basics.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.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.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 / static hidden for output shaping. Covers why merge() on a persisted model can't retarget a write via a spoofed id, and why static hidden — not toJsonColumns/resource alone — is the field that's guaranteed to never serialize. Load when creating a model file, adding accessors, shaping serialized output, or hiding a password/token from responses.
-
-### `define-relations.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.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.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; nested calls flat-join the outer transaction. Also covers row locking (`lockForUpdate({ skipLocked })` → `FOR UPDATE SKIP LOCKED`, Postgres-only — the concurrent queue-claim shape), transaction-aware raw SQL (`Model.raw` / `DataSource.raw` → `RawQueryResult`) and the Postgres `nativeArrayColumns` connection option. Load when two or more writes must succeed or fail together (creating parent + children, transferring balances, multi-step state machines), locking rows against concurrent workers, or when running raw SQL.
-
-### `paginate-results.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.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(rows, { bulk, batchSize }) / Model.findAndUpdate / Model.delete for bulk. atomic() / findAndUpdate() / findOneAndUpdate() / findAndReplace() / findOneAndDelete() sanitize their filter argument the same way where() does. Load when incrementing counters under concurrency, fast bulk inserts (native multi-row insertMany), bulk ops without N+1, or single-document atomic mutations without a full transaction.
-
-### `query-data.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 / .whereRaw / .pluck / .firstOrFail / scopes) via .query() or chained off .where(). Covers filter safety (where() rejects $-prefixed keys, whereRaw() string mode rejects $where, whereLike/whereSearch match strings literally). Load when filtering, fetching by ID, getting a single match, ordering, or checking whether a filter/search built from request data is safe.
-
-### `run-cascade-cli.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.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.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.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.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.