ts-prorm-orm 1.2.3 → 2.1.0

package/CHANGELOG.md

@@ -5,16 +5,279 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [1.2.3]
+## [2.1.0] - 2026-09-07
+
+### Documentation
+
+- **The documentation is now a guided path rather than a reference dump.** A
+  landing page, a getting-started tutorial that runs as written, a stated
+  reading order with an editorial hand-off at the end of each page, and an
+  overview page for every major section. The dialect and store indexes listed
+  12 of 27 and 12 of 88 pages respectively; both are now complete and generated
+  from the pages themselves so they cannot drift.
+
+- **An API reference generated from the source.** TypeDoc was configured but
+  never ran, leaving 11,098 TSDoc blocks invisible; it now builds in CI and
+  ships at `/reference`. TSDoc coverage of exported declarations rose from
+  81.2% to 86.0%, and 97 usage examples that TypeDoc had been parsing as block
+  tags — rendering as mangled tag soup — are fenced correctly.
+
+- **The viewer gained** collapsible grouped navigation (stores was 89 links in
+  one flat list), breadcrumbs, in-page contents, heading anchors, callouts,
+  mermaid diagrams and Ace syntax highlighting — with eleven Playwright smoke
+  tests covering it, since it is the one component that cannot be verified
+  without a browser.
+
+- **All Vercel content is gone.** The 12 guides under `guides/docker/` were
+  written around Vercel Sandbox despite the directory name; each is rewritten
+  against real Docker using the images and credentials `docker-compose.test.yml`
+  already uses. `runbooks/rollback.md` described three things that no longer
+  exist and now documents the GitLab Pages deploy. What stays is
+  `stores/vercel-kv.md`: Vercel KV is a supported data store, not deployment
+  cruft.
+
+### Security
+
+- **Cleared every HIGH and CRITICAL dependency advisory** (40 issues / 123
+  vulnerable paths at the start, including one Critical). `npm audit` goes from
+  46 findings (19 high, 2 critical) to 16 (0 high, 0 critical); everything left
+  is moderate or low.
+
+  Most of it was lockfile staleness rather than unfixable advisories — the
+  declared ranges already permitted the patched versions. Refreshing within
+  those ranges moved `undici` 7.28.0 → 7.29.1 (the Critical: improper
+  certificate validation), `tar` 6.2.1 → 7.5.22, `mysql2` 3.20.0 → 3.24.3,
+  `mariadb` 3.5.2 → 3.5.4, `@xmldom/xmldom` 0.9.10 → 0.9.12 (11 advisories),
+  `thrift` 0.23.0 → 0.24.0, `protobufjs` 7.6.4 → 7.6.6, `browserslist` 4.28.1 →
+  4.28.9, `fast-xml-parser` 5.9.3 → 5.11.1 and `brace-expansion` to 1.1.18 /
+  2.1.4 / 5.0.9.
+
+  Three `overrides` cover transitives whose parents pin a vulnerable version:
+  `adm-zip` ^0.6.0 (pinned by `ibm_db`), `toml` ^5.0.0 (pinned by
+  `snowflake-sdk` at ^3.0.0) and `node-gyp` ^11.4.2, which pulls modern
+  `cacache` (19.0.1), `make-fetch-happen` (14.0.3) and `tar` 7.x through the
+  native-build toolchain. Note that npm `overrides` apply to this repository's
+  own install and are **not** inherited by packages that depend on
+  ts-prorm-orm.
+
+  npm proposed "fixes" that were actually downgrades — `ibm_db` 4.0.1 → 3.1.0
+  and `snowflake-sdk` 3.0.0 → 1.11.0. Those were rejected; the overrides above
+  address the same advisories without giving up a major version of DB2 or
+  Snowflake support.
+
+- **Two advisories are accepted rather than fixed, in a documented `.snyk`
+  policy.** Both are HIGH, transitive, and have no upgrade available today; the
+  other 38 issues were fixed by moving to patched versions, not ignored. Each
+  entry carries a reason and a 2026-12-06 expiry so it has to be re-argued
+  rather than quietly living forever.
+
+  `adm-zip` (Symlink Attack) has **no fixed version at all** — 0.6.0 is the
+  latest release. It arrives only through `ibm_db`, and only in
+  `installer/driverInstall.js`, which unzips IBM's own CLI driver bundle at
+  install time; nothing in `ibm_db/lib` reaches it, and `allowScripts` does not
+  approve `ibm_db`, so that installer never runs here anyway.
+
+  `@opentelemetry/core` (unbounded resource allocation) *is* fixed in 2.8.0,
+  but that fix is unreachable: `@google-cloud/spanner` depends on the OTel 1.x
+  API, and `@opentelemetry/resources@1.30.1` pins core to exactly 1.30.1, so
+  core cannot move alone. Overriding the whole stack to 2.x was tried and
+  verified to break Spanner outright — `require('@google-cloud/spanner')`
+  throws `ExplicitBucketHistogramAggregation is not a constructor` — so the
+  override was reverted rather than shipping a broken Spanner dialect.
+
+### Removed
+
+- **`sqlite3` is no longer a dependency.** Nothing in the codebase imported it
+  — SQLite runs on `better-sqlite3` (and `bun:sqlite` under Bun), which the
+  driver loader selects at runtime. It was a hard dependency, so every consumer
+  compiled a native addon for a package that was never loaded, and it dragged
+  in the vulnerable `node-gyp` 8.x / `cacache` 15.x / `tar` 6.2.1 toolchain.
+  Installs are smaller and one native build lighter.
+
+- **The CI pipeline drops from 77 jobs to 13.** `db.gitlab-ci.yml` and its 59
+  `mirror:*` jobs are gone: each pulled a multi-gigabyte database image through
+  docker-in-docker and pushed it to this project's registry, purely so the
+  Docker guides could pull from a registry we control — and those guides now
+  pull from Docker Hub directly, so the jobs had no remaining consumer. The 18
+  `db-*` category stages went with them.
+
+  Also removed: the `test` shard matrix, `test:coverage`, `tf:plan` and
+  `tf:drift`. **The test suite no longer runs in CI**; `build:node22` (tsc) and
+  `lint` are the automated gates on a push. The full suite still runs through
+  `prepublishOnly` on the tag-triggered `publish` job — but not on
+  `publish:npm`, which uses `--ignore-scripts`.
+
+### Changed
+
+- **Pinned `@qdrant/js-client-rest` to `~1.18.0`.** 1.19.0 removed `search()`
+  and `searchBatch()` in a *minor* release; their replacements (`query()` /
+  `queryBatch()`) take a different request shape and return `{ points }`
+  instead of an array, so adopting them would change the public signature of
+  `QdrantStore.searchBatch()`. Pinning keeps the API stable and still clears
+  the advisory, because 1.18.0's `undici ^6.24.0` range resolves to the fixed
+  6.28.1. Migrating to the query API is deliberate future work.
+
+### Fixed
+
+- **`allowScripts` no longer silently skips the native build.** It approved
+  `better-sqlite3@12.8.0` by exact version, so refreshing the lockfile to
+  12.11.1 blocked the `node-gyp` install script — leaving no compiled binding
+  and failing 155 suites / 2,283 tests with no obvious cause. npm rejects
+  semver ranges in this field, so the entry now lists exact versions joined by
+  `||`. Note that after changing it you must `npm rebuild`, because npm only
+  runs install scripts when it actually (re)installs a package.
+- **`sbom` no longer fails on peer-dependency noise.** `cyclonedx-npm` shells
+  out to `npm ls`, which exits `ELSPROBLEMS` because the root install uses
+  `--legacy-peer-deps`; `--ignore-npm-errors` tolerates it.
+- **`snyk:code` no longer blocks on a missing entitlement.** Snyk Code is
+  separately licensed and returns `403 Forbidden (SNYK-CLI-0000)` with no
+  findings when the org lacks it — a licensing state, not a security result.
+- **The documentation site can actually deploy.** `pages` had no `needs:`, so
+  it waited on every earlier stage and was silently blocked by unrelated
+  security-scan failures. It is decoupled with `needs: []`; the security jobs
+  still gate the pipeline, just not the docs.
+
+## [2.0.0]
+
+### Breaking
+
+- **JSON/JSONB columns now return parsed values on every dialect.** Previously
+  the PostgreSQL and MySQL drivers returned an object while SQLite (and any
+  dialect storing JSON as TEXT) returned the raw string. Reads are now
+  consistent, which means **code that called `JSON.parse` on the result under
+  SQLite must drop that call** — it will now be parsing an object.
+
+  This is the only change requiring action on upgrade. Text that isn't valid
+  JSON is still returned as-is rather than throwing, so rows written by earlier
+  versions read back correctly.
+
+### Changed
+
+- **JSON/JSONB columns now round-trip losslessly, and read back as parsed
+  values on every dialect.** Two separate problems, fixed together.
+
+  *Reads were dialect-specific.* The PostgreSQL and MySQL drivers already
+  returned an object; SQLite (and anything else storing JSON as TEXT) returned
+  the raw string, so the same model code behaved differently per engine.
+  `findAll`/`findOne`/`findByPk` now parse the string form everywhere.
+  **If you were calling `JSON.parse` yourself on SQLite, remove it** — the value
+  arrives parsed. Values that are already objects are untouched, and text that
+  isn't valid JSON is returned as-is rather than throwing, so rows written
+  before this release still read back correctly.
+
+  *Writes were asymmetric with reads.* A string value was written to the column
+  **unencoded** while the read side parsed unconditionally, so any string that
+  happened to be valid JSON changed type on the way back: `'123'` returned the
+  number `123`, `'true'` a boolean, `'{"a":1}'` an object, and
+  `'12345678901234567890'` came back as `12345678901234567000` — silent
+  precision loss. It also wrote invalid JSON on PostgreSQL, which rejects a bare
+  `hello` for a `json` column. Every value is now encoded on write, strings
+  included, in both the `define()` and class-based paths.
+
+- **JSON/JSONB values were not serialized on write at all in some paths.** A
+  plain object survived by accident (the dialect's value escaper stringifies
+  objects), but an array was expanded into the `(a, b)` IN-list form and
+  produced invalid SQL. `create`, `bulkCreate`, `update` and `upsert` now
+  serialize explicitly.
 
 ### Fixed
 
+- **`FindOptions.lock` never reached the dialect.** `findAll({ lock: 'UPDATE',
+  transaction: t })` compiled to a plain SELECT, so code written to serialize
+  concurrent updates took no lock at all. It is now forwarded, and PostgreSQL /
+  MySQL emit `FOR UPDATE` / `FOR SHARE` / `LOCK IN SHARE MODE` as documented.
+  Dialects without row-level locking (SQLite) still ignore it.
+- **`FindOptions.union` / `unionType` were silently no-ops** on models built by
+  `prorm.define()` — the branches were declared, documented and compiled by the
+  dialects, but never passed to them, so only the main query ran.
+- **`FindOptions.using` never worked.** It resolved the target through
+  `prorm.connectionManager`, which nothing ever set, so every call threw
+  `Connection 'x' not found. Available: none`; the class-based path then called
+  `.get()` on a plain object. `ConnectionManager.addConnection()` now registers
+  itself on the instance it creates, and `using` is implemented on both query
+  paths.
 - **`raw: true` was accepted and ignored.** Rows came back as full model
   instances carrying `save`/`update`/`destroy` and internal bookkeeping fields
   — slower than asked for, and wrong for grouped aggregates that correspond to
   no model instance. It now returns plain row objects.
 - `normalizeOperatorKeys` is exported from the package root, alongside the
   `operatorToWhereKey` and `getOperatorString` helpers it belongs with.
+- **Row locking never compiled from the object form.** `lock: { level: 'UPDATE' }`
+  — and any object carrying `nowait` / `skipLocked` — emitted no lock clause at
+  all. Every documented shape now compiles across 9 dialects, including SQL
+  Server's table-hint syntax (`WITH (UPDLOCK, ROWLOCK, READPAST)`). A level a
+  dialect lacks throws naming the supported levels.
+- **Composite unique constraints were never emitted.** Neither the `uniqueKeys`
+  model option nor the attribute-level `uniqueKey` grouping produced any SQL, so
+  uniqueness the model declared was never enforced by the database. Worse,
+  `sync({ alter: true })` *destroyed* constraints that had been emitted, because
+  SQLite implements `changeColumn` by rebuilding the table and the rebuild
+  dropped the `UNIQUE` clause. Both declaration forms now emit a real
+  constraint, and declared keys are re-applied after an alter.
+- **Partial indexes.** `IndexOptions.where` compiled to bound placeholders,
+  which no database accepts in a `CREATE INDEX` predicate. Db2, SAP HANA and
+  ClickHouse silently dropped the predicate and returned an **unfiltered**
+  index; MariaDB and Oracle emitted a `WHERE` clause they have never accepted.
+  Predicates are now inlined as escaped literals where supported, and dialects
+  without partial indexes throw with the reason.
+- **`ORDER BY` was broken on three dialects.** `[['name','DESC']]` produced
+  `ORDER BY [0] NAME, [1] DESC` on SQL Server and Snowflake; on Oracle a plain
+  `'name'` emitted one term per *character*. The `asc()` / `desc()` / `random()`
+  helpers were silently ignored on every dialect and on all four graph
+  dialects. `random()` now resolves per engine — `NEWID()` on SQL Server, where
+  `RAND()` is a per-query constant and would not shuffle at all.
+- **Two filtering `include`s on the same parent column** merged into a shape the
+  where-builders don't recognise, collapsed to `"id" = ?`, and returned one
+  arbitrary parent.
+- **`{ all: true }` includes** were never expanded, and did not compose with
+  `required: true`.
+- **A bare-model include** (`include: [Post]`) threw a `TypeError` at the top
+  level and silently loaded nothing when nested; 11 documented `IncludeOptions`
+  fields were being dropped when include entries were rebuilt.
+- **`findAndCountAll` ignored `union`**, so `count` described only the main
+  branch while `rows` covered all of them.
+- **Foreign-key check toggling emitted MySQL syntax on PostgreSQL.** It now
+  routes per dialect family, and dialects with no session-level switch throw
+  naming their own alternative.
+- **The published package could ship a stale build.** `npm run build` was a
+  plain `tsc`, which emits but never deletes, so a leftover `dist/logging.js`
+  from a removed source file shadowed `dist/logging/index.js` — Node resolves a
+  file before a directory — and the built package threw
+  `logQuery is not a function` on `bulkCreate`. The test suite could not catch
+  it, because it runs against `src/`. `build` now cleans first, and
+  `check:package` fails the publish on any stale output.
+
+### Added
+
+- **30 previously unreachable exports.** `src/cache`, `src/audit`,
+  `src/prisma-migrate`, the `@Audit` decorator, `GraphCapabilityError` and
+  `DataLineage` were implemented but not exported, and the `exports` map allowed
+  no deep imports either. Five colliding cache type names are aliased so no
+  existing export changed meaning. `ts-prorm-orm/cache`, `/audit`, `/graph` and
+  `/prisma-migrate` subpaths expose them under their real names.
+- **Bun support.** The SQLite dialect now resolves its driver per runtime:
+  `better-sqlite3` on Node, the built-in `bun:sqlite` on Bun. Bun needs no
+  native build step, and under Bun the better-sqlite3 addon may not be
+  installable at all. The two APIs differ in one place — bun:sqlite has no
+  `db.pragma()` — so the driver module adds it, keeping a single shape for the
+  dialect to code against with no runtime branching in the SQL layer. Under Bun
+  it still falls back to better-sqlite3 if that is what a project already
+  depends on. `scripts/bun-smoke.ts` exercises CRUD, operators, eager loading,
+  ordering, JSON, aggregates, paranoid deletes and transactions on Bun.
+- **Documentation.** 29 developer guides plus an index, with every SQL example
+  captured from the running code rather than written from memory.
+- **Tests.** ~4,000 connection-free tests across dialects, models, query
+  builders, compliance, optimizers, schema, graph and the CLI. `collectCoverageFrom`
+  now scopes coverage to shipped source (`src/test.ts` was inflating the
+  denominator despite being excluded from the build); no coverage threshold is
+  enforced.
+
+### Removed
+
+- **`docs-next`** and its entire Vercel deployment pipeline. Documentation is
+  now a static React viewer published to GitLab Pages, and database image
+  mirroring moved to the project's own GitLab Container Registry.
+
 
 ## [1.2.2]
 
@@ -42,6 +305,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - **`avg()`** — the one standard aggregate that was missing.
+- Removed `src/hooks/` — a 488-line model-level hook system imported by nothing
+  and exported from nowhere, the third such parallel implementation found (after
+  the association decorators and the duplicate eager-loaders). Its `HookName`
+  union was salvaged into `core/types`.
 - `exports` now permits `ts-prorm-orm/package.json`, which build tooling and
   version checks commonly read.
 
@@ -142,6 +409,69 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Fixed
+
+- **Query logging fired twice and ignored per-query overrides.** The user's
+  `logging` callback was handed to the internal Logger as well as being invoked
+  by the query path, so it ran on both - and the Logger's copy honoured no
+  per-query setting, making `findAll({ logging: false })` log anyway. The
+  internal Logger now handles only slow-query detection and its own levels.
+- **Four operations logged nothing at all.** `count`, `bulkCreate`, `increment`
+  and the aggregates never emitted a line, so turning logging on showed an
+  incomplete picture of what the ORM was doing. Every operation now routes
+  through one path.
+- **`instance.validate({ hooks: true })` ran no hooks.** It read a
+  `_hooksManager` property that nothing ever assigned, so the flag was accepted
+  and both `beforeValidate` and `afterValidate` were skipped. Both call sites
+  (prorm.ts and models/model.ts) now use the model's declared hooks, the same
+  source every other lifecycle hook comes from.
+
+### Added
+
+- **Sequelize-compatible query logging.** `logging` accepts `false`, `true` or a
+  `(sql, timing)` function at instance level, overridable per query - so one
+  noisy call can be traced without enabling logging globally, and one call can
+  be silenced without disabling it. Adds `benchmark` (append elapsed time) and
+  `logQueryParameters` (append bound values, off by default since bound values
+  routinely contain credentials). The resolution logic lives in
+  `src/logging/query-logging.ts` and is exported: `logQuery`,
+  `resolveQueryLogger`, `formatQueryLog`.
+- **`unset<Association>()` on belongsTo** — clears the foreign key and persists
+  it. `set<Association>(null)` does the same thing and now explicitly accepts
+  null, but reads as an assignment rather than a removal.
+- **`HookName` / `ModelHookMap` types** — hook names as a union rather than
+  `string`, so a misspelled hook is a compile error instead of a callback that
+  silently never runs.
+- **`@AbstractModel`** — a base class that defines fields shared by several
+  models without getting a table of its own. Columns declared on it, and any
+  `@PrimaryKey` / `@AutoIncrement` / defaults on them, are inherited by the
+  concrete models that extend it; a subclass may redeclare a column to override
+  it. Passing the abstract class to `addModel()` is an error naming the class.
+- **Finders**: `findOneOrFail` / `findByPkOrFail` (throw `EmptyResultError`
+  rather than returning null), `findLast` (inverts the ordering), `exists(where)`
+  (a COUNT rather than fetching a row), and `findInBatches` / `findEach` for
+  walking a large set without holding it in memory. Batching pages by primary
+  key rather than OFFSET, so per-batch cost stays flat and concurrent writes
+  cannot cause a page to be skipped.
+- **Eleven lifecycle hooks that never fired for model-level operations**:
+  `beforeUpdate`/`afterUpdate`, `beforeDestroy`/`afterDestroy`,
+  `beforeSave`/`afterSave`, `beforeFind`/`afterFind`, `beforeCount`, and
+  `beforeUpsert`/`afterUpsert`. They existed for instance methods only, so
+  `Model.update(...)` bypassed them entirely. `beforeFind` may return replacement
+  options and `afterFind` a replacement result set.
+- **`Model.increment()` / `Model.decrement()`** — add to or subtract from
+  numeric columns with `SET n = n + 1` in a single statement, so two concurrent
+  callers each apply their delta. Previously only per-instance helpers existed,
+  leaving a read-modify-write that silently drops one of two simultaneous
+  updates. Accepts a column, a list, or a per-column map; honours `where` and
+  paranoid filtering.
+- **`Model.bulkUpdate(rows)`** — write different values to many rows in one
+  statement, compiled as a `CASE` per column (portable across every supported
+  dialect) rather than one UPDATE per row. Columns a row omits keep their
+  current value; rows not listed are untouched. Identify rows by a non-primary
+  column with `{ key }`.
+
+
 ### Comprehensive Feature Reference
 
 This section provides a complete reference of all ORM features organized by category.

package/README.md

@@ -29,6 +29,13 @@ A TypeScript ORM supporting multiple database dialects with full TypeScript supp
 - **Validation**: Built-in and custom validators
 - **Stored Procedures**: Create and call stored procedures (across supported dialects)
 - **Triggers**: Database triggers with FOR EACH ROW and WHEN clauses (across supported dialects)
+- **Query logging**: Sequelize-compatible `logging` (`false` / `true` / a
+  `(sql, timing)` function), overridable per query, plus `benchmark` for elapsed
+  time and `logQueryParameters` for bound values. Every operation logs, not just
+  some
+- **Bulk writes**: `increment`/`decrement` do the arithmetic in the database, so
+  concurrent updates don't lose each other; `bulkUpdate` writes different values
+  to many rows in one statement instead of one round trip per row
 - **Aggregates**: `count`, `sum`, `avg`, `min`, `max` — all issuing real SQL
   aggregates and honouring `where`, scopes, soft-deletes and relation filters;
   `group` + `having` for grouped results
@@ -646,29 +653,30 @@ npm run diagram:model
 
 ## Documentation
 
-Full documentation is available in the `docs/` directory:
-
-- [Getting Started](./docs/) - Main documentation entry point
-- [Dialects](./docs/dialects/) - Database-specific documentation
-  - [SQLite](./docs/dialects/sqlite.md)
-  - [MySQL](./docs/dialects/mysql.md)
-  - [PostgreSQL](./docs/dialects/postgres.md)
-  - [MariaDB](./docs/dialects/mariadb.md)
-  - [Oracle](./docs/dialects/oracle.md)
-  - [MSSQL](./docs/dialects/mssql.md)
-- [API Reference](./docs/api/) - API documentation
-  - [Models](./docs/api/models.md)
-  - [Query Builder](./docs/api/queries.md)
-  - [Hooks](./docs/api/hooks.md)
-  - [Associations](./docs/api/associations.md)
-
-Additional documentation:
-- [Models](./docs/MODELS.md) - Model definition
-- [Migrations](./docs/MIGRATIONS.md) - Database migrations
-- [Associations](./docs/ASSOCIATIONS.md) - Relationship types
-- [Hooks](./docs/HOOKS.md) - Lifecycle hooks
-- [Stored Procedures](./docs/STORED_PROCEDURES.md) - Advanced database features
-- [Triggers](./docs/TRIGGERS.md) - Database triggers
+Full documentation is in the [`docs/`](./docs/README.md) directory — start
+there for the complete index.
+
+**Core**
+- [Defining models](./docs/guides/models.md) · [Data types](./docs/guides/data-types.md) · [Querying](./docs/guides/querying.md) · [Query operators](./docs/guides/query-operators.md)
+- [SQL function builders](./docs/guides/sql-functions.md) · [Associations](./docs/guides/associations.md) · [Eager loading](./docs/guides/eager-loading.md) · [Scopes](./docs/guides/scopes.md) · [Hooks](./docs/guides/hooks.md) · [Validation](./docs/guides/validation.md) · [Virtual fields](./docs/guides/virtual-fields.md)
+- [Transactions](./docs/guides/transactions.md) · [Bulk operations](./docs/guides/bulk-operations.md) · [Raw queries](./docs/guides/raw-queries.md) · [Streaming](./docs/guides/streams.md) · [Error handling](./docs/guides/error-handling.md)
+
+**Schema**
+- [Indexes & constraints](./docs/guides/indexes-and-constraints.md) · [Schema objects](./docs/guides/schema-objects.md) (views, triggers, procedures, sequences, RLS, partitions)
+- [Migrations](./docs/guides/migrations.md) · [QueryInterface](./docs/guides/query-interface.md) · [Schema diffing](./docs/guides/schema-diffing.md) · [Prisma import](./docs/guides/prisma-import.md)
+
+**Connections & performance**
+- [Connection pooling](./docs/guides/connection-pooling.md) · [Multiple databases](./docs/guides/multiple-databases.md) · [Read replicas](./docs/guides/replication.md)
+- [Caching](./docs/guides/caching.md) · [Query optimization](./docs/guides/query-optimization.md) · [Logging](./docs/guides/logging.md)
+
+**Extending & operating**
+- [Decorators](./docs/guides/decorators.md) · [TypeScript types](./docs/guides/typescript-types.md) · [External fields](./docs/guides/external-fields.md) · [SQL constants](./docs/guides/sql-constants.md) · [Extension catalogue](./docs/guides/extensions.md)
+- [Audit logging](./docs/guides/audit-logging.md) · [User management](./docs/guides/user-management.md) · [Compliance](./docs/guides/compliance.md) · [Foreign data wrappers](./docs/guides/foreign-data-wrappers.md) · [Runbooks](./docs/runbooks/README.md)
+
+**Databases & tooling**
+- [Database types](./docs/database-types.md) · [SQL dialects](./docs/dialects/README.md) ([SQLite](./docs/dialects/sqlite.md), [PostgreSQL](./docs/dialects/postgres.md), [MySQL](./docs/dialects/mysql.md), [MariaDB](./docs/dialects/mariadb.md), [Oracle](./docs/dialects/oracle.md), [MSSQL](./docs/dialects/mssql.md), …)
+- [Store adapters](./docs/stores/README.md) · [Graph databases](./docs/guides/graph-databases.md) · [SQLite advanced](./docs/guides/sqlite-advanced.md)
+- [CLI](./docs/guides/cli.md) · [Diagrams](./docs/diagrams/README.md) · [Docker & sandboxes](./docs/guides/docker/)
 
 ### Architecture / Component Guides
 
@@ -676,7 +684,7 @@ In-depth, code-level reference docs for each major subsystem, living alongside t
 
 - [Dialects](src/dialects/README.md) - The `Dialect` interface and per-database (SQLite/MySQL/PostgreSQL/MariaDB/Oracle/MSSQL/CockroachDB/Redshift/Db2/Snowflake/ClickHouse/DuckDB/HANA/Spanner) implementations of connections, DDL, views, partitioning, RLS, and query building.
 - [Models](src/models/README.md) - The model layer: attribute/data types, `prorm.define()`, associations, scopes, indexes/constraints, and the model registry.
-- [Query Builders](src/query-builders/README.md) - Translates `where`/`order`/`limit`/`include` options into dialect-specific SQL strings and bound parameter values. Includes a typed SQL function-builder library (`src/query-builders/functions/**` - window functions, date/time, JSON paths, string/math functions, CASE expressions, cross-dialect aggregates, full-text search) usable via `import { ... } from 'ts-prorm-orm'`; see [SQL Functions](docs/query-features/queries.md#sql-functions) for worked examples.
+- [Query Builders](src/query-builders/README.md) - Translates `where`/`order`/`limit`/`include` options into dialect-specific SQL strings and bound parameter values. Includes a typed SQL function-builder library (`src/query-builders/functions/**` - window functions, date/time, JSON paths, string/math functions, CASE expressions, cross-dialect aggregates, full-text search) usable via `import { ... } from 'ts-prorm-orm'`; see [`src/query-builders/README.md`](src/query-builders/README.md) for the function list.
 - [Extension Catalog](src/extensions/README.md) - A discoverability reference (not executable code) of ~124 verified real extensions/plugins/licensed features across dialects, queryable via `findExtension()`/`listExtensionsForDialect()`/`listExtensionsByCategory()`/`searchExtensions()`.
 - [Query Optimizers](src/query-optimizers/README.md) - Opt-in performance tooling (query hints, explain plans, slow-query logging, batch optimization, prepared-statement/result caching).
 - [Migrations](src/migrations/README.md) - Migration files, the `Migrator`, `PrormMeta` history tracking, seeders, `QueryInterface`, and schema diffing (`src/schema/`).

package/dist/compliance/data-classifier.d.ts

@@ -10,6 +10,7 @@
  *   PIPL, AI Act EU, GDPR Art 25/30/32, and data classification requirements.
  *
  * Usage:
+ * ```ts
  *   // Tag fields with sensitivity levels:
  *   @Classify('PII')
  *   @FieldClassification('email', 'PII')
@@ -25,6 +26,7 @@
  *
  *   // Auto-discover fields by name patterns:
  *   DataClassifier.autoDiscover(User, ['ssn', 'social', 'dob', 'card', 'password']);
+ * ```
  */
 export type SensitivityLevel = 'PUBLIC' | 'INTERNAL' | 'CONFIDENTIAL' | 'SECRET' | 'TOP_SECRET';
 export type DataCategory = 'PII' | 'PHI' | 'PCI' | 'PCI_PAN' | 'FINANCIAL' | 'HEALTH' | 'BIOMETRIC' | 'CUI' | 'SENSITIVE';
@@ -45,16 +47,20 @@ export interface ClassificationMetadata {
 /**
  * Classify the entire model (applies to all fields, use field-level for specifics).
  *
+ * ```ts
  *   @Classify('CONFIDENTIAL')
  *   class FinancialRecord extends Model { ... }
+ * ```
  */
 export declare function Classify(level: SensitivityLevel): (target: Function) => void;
 /**
  * Classify a specific field.
  *
+ * ```ts
  *   @FieldClassification('email', 'PII')
  *   @FieldClassification('ssn', 'PHI', { level: 'SECRET', regulations: ['HIPAA'] })
  *   @FieldClassification('creditCard', 'PCI_PAN', { level: 'TOP_SECRET' })
+ * ```
  */
 export declare function FieldClassification(field: string, category: DataCategory, options?: Partial<ClassificationMetadata>): (target: Function) => void;
 /**

package/dist/compliance/data-classifier.js

@@ -11,6 +11,7 @@
  *   PIPL, AI Act EU, GDPR Art 25/30/32, and data classification requirements.
  *
  * Usage:
+ * ```ts
  *   // Tag fields with sensitivity levels:
  *   @Classify('PII')
  *   @FieldClassification('email', 'PII')
@@ -26,6 +27,7 @@
  *
  *   // Auto-discover fields by name patterns:
  *   DataClassifier.autoDiscover(User, ['ssn', 'social', 'dob', 'card', 'password']);
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataClassifier = void 0;
@@ -54,8 +56,10 @@ function getClassifications(target) {
 /**
  * Classify the entire model (applies to all fields, use field-level for specifics).
  *
+ * ```ts
  *   @Classify('CONFIDENTIAL')
  *   class FinancialRecord extends Model { ... }
+ * ```
  */
 function Classify(level) {
     return function (target) {
@@ -68,9 +72,11 @@ function Classify(level) {
 /**
  * Classify a specific field.
  *
+ * ```ts
  *   @FieldClassification('email', 'PII')
  *   @FieldClassification('ssn', 'PHI', { level: 'SECRET', regulations: ['HIPAA'] })
  *   @FieldClassification('creditCard', 'PCI_PAN', { level: 'TOP_SECRET' })
+ * ```
  */
 function FieldClassification(field, category, options = {}) {
     return function (target) {

package/dist/compliance/data-lineage.d.ts

@@ -25,9 +25,11 @@
  *   // Get transformation history:
  *   const transforms = await DataLineage.getTransformations(orderId, 'Orders');
  *
+ * ```ts
  *   // Using the decorator:
  *   @LineageTrack({ fields: ['amount', 'total'] })
  *   class Order extends Model { ... }
+ * ```
  */
 import { ModelStatic, Prorm } from '../prorm';
 /** The origin of data - how it entered the system */
@@ -128,8 +130,10 @@ export interface LineageTrackOptions {
 /**
  * Decorator to mark fields for lineage tracking.
  *
+ * ```ts
  *   @LineageTrack({ fields: ['amount', 'total', 'tax'] })
  *   class Order extends Model { ... }
+ * ```
  */
 export declare function LineageTrack(options?: LineageTrackOptions): (target: Function) => void;
 /**

package/dist/compliance/data-lineage.js

@@ -26,9 +26,11 @@
  *   // Get transformation history:
  *   const transforms = await DataLineage.getTransformations(orderId, 'Orders');
  *
+ * ```ts
  *   // Using the decorator:
  *   @LineageTrack({ fields: ['amount', 'total'] })
  *   class Order extends Model { ... }
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataLineage = void 0;
@@ -46,8 +48,10 @@ const lineageRegistry = new Map();
 /**
  * Decorator to mark fields for lineage tracking.
  *
+ * ```ts
  *   @LineageTrack({ fields: ['amount', 'total', 'tax'] })
  *   class Order extends Model { ... }
+ * ```
  */
 function LineageTrack(options = {}) {
     return function (target) {

package/dist/compliance/data-masker.d.ts

@@ -15,6 +15,7 @@
  *   DataMasker.maskField(Payment, 'cardNumber', { pattern: 'card-last4', showLast: 4 });
  *   DataMasker.maskField(Customer, 'email', { pattern: 'email' });
  *
+ * ```ts
  *   // Or use the decorator:
  *   @Mask('ssn', { pattern: 'ssn' })
  *   class User extends Model { ... }
@@ -25,6 +26,7 @@
  *
  *   // Or use the automatic hook:
  *   DataMasker.applyHooks(User);
+ * ```
  */
 /** Built-in masking pattern identifiers; see {@link MaskPatternEnum} for the enum form. */
 export type MaskPattern = 'ssn' | 'card-last4' | 'card-first6' | 'email' | 'phone' | 'full' | 'none' | 'custom';
@@ -71,8 +73,10 @@ export declare function getMaskRules(Model: any): MaskRule[];
 /**
  * Decorator to mark a field for masking.
  *
+ * ```ts
  *   @Mask('ssn', { pattern: 'ssn' })
  *   class User extends Model { ... }
+ * ```
  */
 export declare function Mask(field: string, options?: MaskOptions): (target: Function) => void;
 /**

package/dist/compliance/data-masker.js

@@ -16,6 +16,7 @@
  *   DataMasker.maskField(Payment, 'cardNumber', { pattern: 'card-last4', showLast: 4 });
  *   DataMasker.maskField(Customer, 'email', { pattern: 'email' });
  *
+ * ```ts
  *   // Or use the decorator:
  *   @Mask('ssn', { pattern: 'ssn' })
  *   class User extends Model { ... }
@@ -26,6 +27,7 @@
  *
  *   // Or use the automatic hook:
  *   DataMasker.applyHooks(User);
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DataMasker = exports.MaskPatternEnum = void 0;
@@ -197,8 +199,10 @@ function getMaskRules(Model) {
 /**
  * Decorator to mark a field for masking.
  *
+ * ```ts
  *   @Mask('ssn', { pattern: 'ssn' })
  *   class User extends Model { ... }
+ * ```
  */
 function Mask(field, options = {}) {
     return function (target) {

package/dist/compliance/index.d.ts

@@ -15,6 +15,7 @@
  *   import { ComplianceAuditTrail } from './compliance/audit-trail';
  *   ComplianceAuditTrail.enable(prorm, UserModel, { getUserId: () => user.id });
  *
+ * ```ts
  *   // 2. Field-level AES-256-GCM encryption
  *   import { FieldEncryption } from './compliance/field-encryption';
  *   FieldEncryption.configure('32-byte-hex-key');
@@ -65,6 +66,7 @@
  *   import { DataClassifier } from './compliance/data-classifier';
  *   @FieldClassification('email', 'PII') class User extends Model {}
  *   const piiFields = DataClassifier.getPIIFields(User);
+ * ```
  */
 export { ComplianceAuditTrail, AuditTrailOptions } from './audit-trail';
 export { FieldEncryption, configureFieldEncryption, encryptValue, decryptValue, Encrypt, applyEncryptionHooks, getEncryptedFields, } from './field-encryption';
@@ -91,3 +93,5 @@ export { DSARWorkflow, DSARRequest, RequestStatus, RequestType, FulfillmentOptio
 export { PrivacyImpactAssessment, AssessmentStatus, RiskSeverity, PIARecord, RiskRecord, PIACreateOptions, RiskRecordOptions, } from './privacy-impact-assessment';
 export { BackupVerification, BackupSource, BackupConfig, BackupMetadata, VerificationResult, VerificationSchedule, VerificationHistoryEntry, } from './backup-verification';
 export { QueryFirewall, FirewallRule, FirewallRuleType, FirewallMode, FirewallModeEnum, FirewallOptions, QueryAnalysis, QueryOperation, BlockedQuery, getRecommendedRules, FIREWALL_RULES, OWASP_SQL_INJECTION_PATTERNS, CIS_BENCHMARK_RULES, PCI_DSS_RULES, HIPAA_RULES, SOX_RULES, NIST_CSF_RULES, POSTGRESQL_RULES, MYSQL_RULES, MARIADB_RULES, MSSQL_RULES, ORACLE_RULES, SQLITE_RULES, DATABASE_RULES, DatabaseType, FirewallRules, FirewallRuleDecoratorOptions, PostgreSQLFirewall, MySQLFirewall, MariaDBFirewall, MSSQLFirewall, OracleFirewall, SQLiteFirewall, applyFirewallRulesToModel, } from './query-firewall';
+export { DataLineage, LineageTrack, getLineageFields, getLineageOptions, createDerivedRecord, createComputedRecord, applyHooks as applyLineageHooks, } from './data-lineage';
+export type { DataSource, TransformationRecord, LineageRecord, LineageChain, LineageOptions, LineageTrackOptions, } from './data-lineage';