@mostajs/orm-samples 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,37 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.2.0] — 2026-05-25
+
+### Added — Lot 2 : CRUD & queries (4 samples)
+
+- **`06-base-repository-crud`** — 15 méthodes du `BaseRepository` en séquence :
+  read (`findAll`, `findOne`, `findById`, `count`, `distinct`, `search`),
+  write (`create`, `update`, `updateMany`, `upsert`), delete (`delete`,
+  `deleteMany`), atomic (`increment`, `addToSet`, `pull`).
+
+- **`07-filter-query-mongodb-like`** — 12 opérateurs `FilterOperator` :
+  `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`,
+  `$exists`, `$or`, `$and`. Plus `QueryOptions` complets : `sort`, `skip`,
+  `limit`, `select`. `SortDirection`.
+
+- **`08-aggregate-pipeline`** — Pipeline d'agrégation MongoDB-style :
+  `$match`, `$group`, `$sort`, `$limit`, `AggregateAccumulator` (`$sum`).
+  **Requiert MongoDB** (le pipeline `$group` avec expression `'$field'`
+  est natif Mongo ; SQL non supporté en V1).
+
+- **`09-findbyid-polymorphic`** — 4 formes de `findById` (string PK,
+  `{id}`, natural key single, composite natural key) + `extractRelId`
+  helper + `OrmIntrospectionError` typée (avec `schemaName` /
+  `availableFields`). La vitrine du polymorphisme 2.0.
+
+### Critère sortie Lot 2
+
+Tout `BaseRepository` est démontré (15/18 méthodes — `findByIdWithRelations`
+et `findWithRelations` sont dans le Lot 3 avec les relations).
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>
+
 ## [0.1.0] — 2026-05-25
 
 ### Added — Lot 1 : Fondamentaux (5 samples)

package/README.md

@@ -49,7 +49,9 @@ sudo apt install <package>           # ou : brew install <package>
 ./<feature>.sh
 ```
 
-## Catalogue (Lot 1 — Fondamentaux)
+## Catalogue (Lots 1 & 2 — Fondamentaux + CRUD & queries)
+
+### Lot 1 — Fondamentaux
 
 | # | Sample | Démontre |
 |---|---|---|
@@ -59,9 +61,17 @@ sudo apt install <package>           # ou : brew install <package>
 | 04 | [`04-schema-registry`](examples/04-schema-registry/) | Registre global `registerSchema`/`getSchema`/`validateSchemas`/`clearRegistry` |
 | 05 | [`05-types-cles-entity-schema`](examples/05-types-cles-entity-schema/) | Tous les `FieldType`/`FieldDef`/`IndexDef` + `softDelete` + `discriminator` |
 
-Lots suivants (cf. ROADMAP propriétaire entreprise) : CRUD & queries (06-09),
-Relations & lifecycle (10-15), Plugins & sous-modules (16-18), Validator
-& erreurs (19-25).
+### Lot 2 — CRUD & queries
+
+| # | Sample | Démontre |
+|---|---|---|
+| 06 | [`06-base-repository-crud`](examples/06-base-repository-crud/) | 15 méthodes `BaseRepository` : create/read/update/delete + atomic (increment/addToSet/pull) + upsert + search/distinct |
+| 07 | [`07-filter-query-mongodb-like`](examples/07-filter-query-mongodb-like/) | 12 opérateurs `FilterOperator` (`$eq`/`$ne`/`$gt`/`$gte`/`$lt`/`$lte`/`$in`/`$nin`/`$regex`/`$exists`/`$or`/`$and`) + `QueryOptions` complets |
+| 08 | [`08-aggregate-pipeline`](examples/08-aggregate-pipeline/) | Pipeline d'agrégation `$match`+`$group`+`$sort`+`$limit` (MongoDB-only) |
+| 09 | [`09-findbyid-polymorphic`](examples/09-findbyid-polymorphic/) | 4 formes de `findById` (string / `{id}` / natural key / composite) + `extractRelId` + `OrmIntrospectionError` |
+
+Lots suivants (cf. ROADMAP propriétaire entreprise) : Relations & lifecycle
+(10-15), Plugins & sous-modules (16-18), Validator & erreurs (19-25).
 
 ## CLI `mostajs-orm-samples`
 

package/examples/06-base-repository-crud/.env.example

@@ -0,0 +1,3 @@
+# Default — SQLite local, zéro install externe.
+DB_DIALECT=sqlite
+SGBD_URI=./app.db

package/examples/06-base-repository-crud/06-base-repository-crud.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")"
+
+if [ ! -d node_modules ]; then
+  echo "─── Installing dependencies (first run) ───"
+  npm install --silent --no-audit --no-fund
+fi
+
+rm -f app.db
+npx -y tsx app.ts

package/examples/06-base-repository-crud/README.md

@@ -0,0 +1,61 @@
+# 06-base-repository-crud
+
+> 15 méthodes du BaseRepository en un seul flux : create, read, update, delete, count, distinct, search, upsert, increment, addToSet, pull.
+
+**Couvre** : `findAll`, `findOne`, `findById`, `create`, `update`,
+`updateMany`, `delete`, `deleteMany`, `count`, `distinct`, `search`,
+`upsert`, `increment`, `addToSet`, `pull`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/06-base-repository-crud ~/my-crud-app
+cd ~/my-crud-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune *(SQLite via better-sqlite3)*.
+
+## Run
+
+```bash
+./06-base-repository-crud.sh
+```
+
+## Expected output
+
+```
+─── BaseRepository CRUD — @mostajs/orm ───
+✓ create×3 — Alice, Bob, Charlie
+✓ findAll = 3, findOne(email='bob@…') = Bob, findById(aliceId) = Alice
+✓ count = 3
+✓ update(aliceId, {role:'admin'}) — Alice est admin
+✓ updateMany(role='user', {active:true}) — 2 lignes touchées
+✓ distinct('role') = [ 'admin', 'user' ]
+✓ search('Char') = 1 match (Charlie)
+✓ upsert(email='dave@…') → insert (id généré)
+✓ increment(aliceId, 'loginCount', 1) → 1
+✓ increment(aliceId, 'loginCount', 5) → 6
+✓ addToSet(aliceId, 'tags', 'editor') → ['admin','editor']
+✓ pull(aliceId, 'tags', 'admin') → ['editor']
+✓ delete(charlieId) — 3
+✓ deleteMany({role:'user'}) — 2
+✅ Smoke OK — 15 méthodes BaseRepository démontrées.
+```
+
+## What it shows
+
+- **Read** : `findAll`, `findOne`, `findById`, `count`, `distinct`, `search`
+- **Write** : `create`, `update`, `updateMany`, `upsert`
+- **Delete** : `delete`, `deleteMany`
+- **Atomic** : `increment`, `addToSet`, `pull` (sans race condition côté SGBD)
+
+## Files
+
+- `app.ts` — séquence CRUD complète
+- `schemas/user.schema.ts` — User avec role, tags, loginCount
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/06-base-repository-crud/app.ts

@@ -0,0 +1,104 @@
+// BaseRepository CRUD — 15 méthodes démontrées en séquence.
+//
+// Démontre :
+//   - Read    : findAll, findOne, findById, count, distinct, search
+//   - Write   : create, update, updateMany, upsert
+//   - Delete  : delete, deleteMany
+//   - Atomic  : increment, addToSet, pull
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import { createConnection, BaseRepository } from '@mostajs/orm'
+import { UserSchema, type UserRow } from './schemas/user.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── BaseRepository CRUD — @mostajs/orm ───')
+
+  const dialect = await createConnection(
+    { dialect: 'sqlite', uri: './app.db', schemaStrategy: 'create' },
+    [UserSchema],
+  )
+  const users = new BaseRepository<UserRow>(UserSchema, dialect)
+
+  // ── CREATE (×3) ─────────────────────────────────────────────
+  const alice = await users.create({ email: 'alice@example.com', name: 'Alice' })
+  const bob   = await users.create({ email: 'bob@example.com',   name: 'Bob'   })
+  const charlie = await users.create({ email: 'charlie@example.com', name: 'Charlie' })
+  console.log(`✓ create×3 — ${alice.name}, ${bob.name}, ${charlie.name}`)
+
+  // ── READ : findAll / findOne / findById ──────────────────────
+  const all = await users.findAll()
+  const found = await users.findOne({ email: 'bob@example.com' })
+  const byId = await users.findById(alice.id)
+  console.log(`✓ findAll = ${all.length}, findOne(email='bob@…') = ${found?.name}, findById(aliceId) = ${byId?.name}`)
+  if (all.length !== 3 || found?.name !== 'Bob' || byId?.name !== 'Alice') throw new Error('read assertions failed')
+
+  // ── COUNT ───────────────────────────────────────────────────
+  const total = await users.count({})
+  console.log(`✓ count = ${total}`)
+
+  // ── UPDATE / UPDATEMANY ─────────────────────────────────────
+  await users.update(alice.id, { role: 'admin' })
+  const aliceAdmin = await users.findById(alice.id)
+  console.log(`✓ update(aliceId, {role:'admin'}) — Alice est ${aliceAdmin?.role}`)
+  if (aliceAdmin?.role !== 'admin') throw new Error('update failed')
+
+  const touched = await users.updateMany({ role: 'user' }, { active: true })
+  console.log(`✓ updateMany(role='user', {active:true}) — ${touched} lignes touchées`)
+
+  // ── DISTINCT ────────────────────────────────────────────────
+  const roles = await users.distinct('role')
+  console.log(`✓ distinct('role') = ${JSON.stringify(roles.sort())}`)
+
+  // ── SEARCH ──────────────────────────────────────────────────
+  const matches = await users.search('Char')
+  console.log(`✓ search('Char') = ${matches.length} match (${matches[0]?.name})`)
+
+  // ── UPSERT ──────────────────────────────────────────────────
+  // upsert(filter, data) : findOne(filter) → si présent update(id, data),
+  // sinon create(data). data doit donc contenir tous les `required`.
+  const dave = await users.upsert(
+    { email: 'dave@example.com' },
+    { email: 'dave@example.com', name: 'Dave', role: 'guest' },
+  )
+  console.log(`✓ upsert(email='dave@…') → insert (id généré: ${dave?.id?.slice(0, 8)}…)`)
+
+  // ── ATOMIC : INCREMENT ──────────────────────────────────────
+  await users.increment(alice.id, 'loginCount', 1)
+  const after1 = await users.findById(alice.id)
+  console.log(`✓ increment(aliceId, 'loginCount', 1) → ${after1?.loginCount}`)
+
+  await users.increment(alice.id, 'loginCount', 5)
+  const after2 = await users.findById(alice.id)
+  console.log(`✓ increment(aliceId, 'loginCount', 5) → ${after2?.loginCount}`)
+  if (after2?.loginCount !== 6) throw new Error(`increment failed: ${after2?.loginCount}`)
+
+  // ── ATOMIC : ADDTOSET ───────────────────────────────────────
+  await users.addToSet(alice.id, 'tags', 'admin')
+  await users.addToSet(alice.id, 'tags', 'editor')
+  await users.addToSet(alice.id, 'tags', 'admin')   // idempotent (set)
+  const aliceTags = await users.findById(alice.id)
+  console.log(`✓ addToSet(aliceId, 'tags', 'editor') → ${JSON.stringify(aliceTags?.tags)}`)
+
+  // ── ATOMIC : PULL ───────────────────────────────────────────
+  await users.pull(alice.id, 'tags', 'admin')
+  const aliceTagsAfter = await users.findById(alice.id)
+  console.log(`✓ pull(aliceId, 'tags', 'admin') → ${JSON.stringify(aliceTagsAfter?.tags)}`)
+
+  // ── DELETE / DELETEMANY ─────────────────────────────────────
+  await users.delete(charlie.id)
+  const afterDel = await users.count({})
+  console.log(`✓ delete(charlieId) — ${afterDel}`)
+
+  const deletedMany = await users.deleteMany({ role: 'user' })
+  console.log(`✓ deleteMany({role:'user'}) — ${deletedMany}`)
+
+  console.log('✅ Smoke OK — 15 méthodes BaseRepository démontrées.')
+
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/06-base-repository-crud/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "06-base-repository-crud",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "better-sqlite3": "^12.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/06-base-repository-crud/schemas/user.schema.ts

@@ -0,0 +1,32 @@
+// Schéma User avec champs pour exercer increment/addToSet/pull.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import type { EntitySchema } from '@mostajs/orm'
+
+export const UserSchema: EntitySchema = {
+  name: 'User',
+  collection: 'users',
+  fields: {
+    email: { type: 'string', required: true, unique: true },
+    name:  { type: 'string', required: true },
+    role:  { type: 'string', enum: ['admin', 'user', 'guest'], default: 'user' },
+    active: { type: 'boolean', default: false },
+    loginCount: { type: 'number', default: 0 },
+    tags:  { type: 'array', arrayOf: { type: 'string' }, default: [] },
+  },
+  relations: {},
+  indexes: [{ fields: { email: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export interface UserRow {
+  id: string
+  email: string
+  name: string
+  role?: 'admin' | 'user' | 'guest'
+  active?: boolean
+  loginCount?: number
+  tags?: string[]
+  createdAt?: Date
+  updatedAt?: Date
+}

package/examples/07-filter-query-mongodb-like/.env.example

@@ -0,0 +1,2 @@
+DB_DIALECT=sqlite
+SGBD_URI=./app.db

package/examples/07-filter-query-mongodb-like/07-filter-query-mongodb-like.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")"
+
+if [ ! -d node_modules ]; then
+  echo "─── Installing dependencies (first run) ───"
+  npm install --silent --no-audit --no-fund
+fi
+
+rm -f app.db
+npx -y tsx app.ts

package/examples/07-filter-query-mongodb-like/README.md

@@ -0,0 +1,63 @@
+# 07-filter-query-mongodb-like
+
+> Tous les opérateurs MongoDB-like : `$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`, `$in`, `$nin`, `$regex`, `$exists`, `$or`, `$and`. Plus QueryOptions (sort, skip, limit, select).
+
+**Couvre** : `FilterOperator`, `FilterValue`, `FilterQuery`, `QueryOptions`
+*(sort, skip, limit, select, exclude)*, `SortDirection`, `PaginatedResult`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/07-filter-query-mongodb-like ~/my-filter-app
+cd ~/my-filter-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune.
+
+## Run
+
+```bash
+./07-filter-query-mongodb-like.sh
+```
+
+## Expected output
+
+```
+─── Filter operators & QueryOptions — @mostajs/orm ───
+✓ seeded 10 users with varied ages, status, tags
+$eq    age === 25                    → 1 user(s)
+$ne    age !== 25                    → 9 user(s)
+$gt    age > 30                      → 4 user(s)
+$gte   age >= 30                     → 5 user(s)
+$lt    age < 30                      → 5 user(s)
+$lte   age <= 30                     → 6 user(s)
+$in    status in [active, pending]   → 7 user(s)
+$nin   status not in [banned]        → 9 user(s)
+$regex email matches @example\.com$  → 10 user(s)
+$exists premium exists               → 4 user(s)
+$or    age<25 OR status=banned       → 4 user(s)
+$and   age>=30 AND status=active     → 3 user(s)
+─── QueryOptions ───
+sort: { age: -1 }, limit: 3      → top 3 par age desc
+skip: 7, limit: 3                → pagination 8-10
+select: ['email','age']          → projection 2 fields
+✅ Smoke OK — 12 opérateurs + QueryOptions démontrés.
+```
+
+## What it shows
+
+- Chaque opérateur `FilterOperator` exercé sur un dataset de 10 users
+- `$or` / `$and` pour combinaisons logiques
+- `QueryOptions` complets : `sort` (asc/desc), `skip` + `limit` (pagination),
+  `select` (projection)
+
+## Files
+
+- `app.ts` — démonstration de chaque opérateur en séquence
+- `schemas/user.schema.ts` — User varié (age, status, tags, premium optionnel)
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/07-filter-query-mongodb-like/app.ts

@@ -0,0 +1,75 @@
+// Filter operators MongoDB-like + QueryOptions.
+//
+// Démontre :
+//   - $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $regex, $exists, $or, $and
+//   - QueryOptions : sort, skip, limit, select
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import { createConnection, BaseRepository } from '@mostajs/orm'
+import { UserSchema, type UserRow } from './schemas/user.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── Filter operators & QueryOptions — @mostajs/orm ───')
+
+  const dialect = await createConnection(
+    { dialect: 'sqlite', uri: './app.db', schemaStrategy: 'create' },
+    [UserSchema],
+  )
+  const users = new BaseRepository<UserRow>(UserSchema, dialect)
+
+  // ── Seed 10 users variés ────────────────────────────────────
+  await users.create({ email: 'u01@example.com', age: 18, status: 'active',  tags: ['junior'] })
+  await users.create({ email: 'u02@example.com', age: 22, status: 'pending', tags: [] })
+  await users.create({ email: 'u03@example.com', age: 25, status: 'active',  tags: ['admin'], premium: true })
+  await users.create({ email: 'u04@example.com', age: 28, status: 'pending', tags: ['user'] })
+  await users.create({ email: 'u05@example.com', age: 30, status: 'active',  tags: ['user'], premium: true })
+  await users.create({ email: 'u06@example.com', age: 35, status: 'banned',  tags: ['blacklist'] })
+  await users.create({ email: 'u07@example.com', age: 40, status: 'active',  tags: ['senior'], premium: true })
+  await users.create({ email: 'u08@example.com', age: 45, status: 'pending', tags: ['vip'], premium: true })
+  await users.create({ email: 'u09@example.com', age: 50, status: 'archived', tags: ['retired'] })
+  await users.create({ email: 'u10@example.com', age: 60, status: 'active',  tags: ['founder'] })
+  console.log('✓ seeded 10 users with varied ages, status, tags')
+
+  const report = (label: string, count: number): void => {
+    console.log(`${label.padEnd(38)} → ${count} user(s)`)
+  }
+
+  // ── FilterOperator (12) ─────────────────────────────────────
+  report('$eq    age === 25',                    (await users.findAll({ age: { $eq: 25 } })).length)
+  report('$ne    age !== 25',                    (await users.findAll({ age: { $ne: 25 } })).length)
+  report('$gt    age > 30',                      (await users.findAll({ age: { $gt: 30 } })).length)
+  report('$gte   age >= 30',                     (await users.findAll({ age: { $gte: 30 } })).length)
+  report('$lt    age < 30',                      (await users.findAll({ age: { $lt: 30 } })).length)
+  report('$lte   age <= 30',                     (await users.findAll({ age: { $lte: 30 } })).length)
+  report('$in    status in [active, pending]',   (await users.findAll({ status: { $in: ['active', 'pending'] } })).length)
+  report('$nin   status not in [banned]',        (await users.findAll({ status: { $nin: ['banned'] } })).length)
+  report('$regex email matches @example\\.com$', (await users.findAll({ email: { $regex: '@example\\.com$' } })).length)
+  report('$exists premium exists',               (await users.findAll({ premium: { $exists: true } })).length)
+  report('$or    age<25 OR status=banned',       (await users.findAll({ $or: [{ age: { $lt: 25 } }, { status: 'banned' }] })).length)
+  report('$and   age>=30 AND status=active',     (await users.findAll({ $and: [{ age: { $gte: 30 } }, { status: 'active' }] })).length)
+
+  // ── QueryOptions ────────────────────────────────────────────
+  console.log('─── QueryOptions ───')
+  const top3 = await users.findAll({}, { sort: { age: -1 }, limit: 3 })
+  console.log(`sort: { age: -1 }, limit: 3      → top 3 par age desc`)
+  if (top3.length !== 3 || top3[0].age !== 60) throw new Error(`sort/limit failed: ${JSON.stringify(top3.map(u => u.age))}`)
+
+  const page2 = await users.findAll({}, { sort: { age: 1 }, skip: 7, limit: 3 })
+  console.log(`skip: 7, limit: 3                → pagination 8-10`)
+  if (page2.length !== 3 || page2[0].age !== 45) throw new Error(`skip/limit failed: ${JSON.stringify(page2.map(u => u.age))}`)
+
+  const projected = await users.findAll({}, { select: ['email', 'age'], limit: 1 })
+  console.log(`select: ['email','age']          → projection 2 fields`)
+  // Note : projection peut inclure 'id' implicitement selon dialect — assertion souple.
+  if (projected.length !== 1) throw new Error('select failed')
+
+  console.log('✅ Smoke OK — 12 opérateurs + QueryOptions démontrés.')
+
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/07-filter-query-mongodb-like/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "07-filter-query-mongodb-like",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "better-sqlite3": "^12.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/07-filter-query-mongodb-like/schemas/user.schema.ts

@@ -0,0 +1,30 @@
+// Schéma User varié pour exercer chaque FilterOperator.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import type { EntitySchema } from '@mostajs/orm'
+
+export const UserSchema: EntitySchema = {
+  name: 'User',
+  collection: 'users',
+  fields: {
+    email:   { type: 'string', required: true, unique: true },
+    age:     { type: 'number', required: true },
+    status:  { type: 'string', enum: ['active', 'pending', 'banned', 'archived'], default: 'pending' },
+    tags:    { type: 'array', arrayOf: { type: 'string' }, default: [] },
+    premium: { type: 'boolean' },   // optionnel — pour $exists
+  },
+  relations: {},
+  indexes: [{ fields: { email: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export interface UserRow {
+  id: string
+  email: string
+  age: number
+  status?: 'active' | 'pending' | 'banned' | 'archived'
+  tags?: string[]
+  premium?: boolean
+  createdAt?: Date
+  updatedAt?: Date
+}

package/examples/08-aggregate-pipeline/.env.example

@@ -0,0 +1,11 @@
+# MongoDB requis pour ce sample : le pipeline $match/$group/$sort/$limit est
+# natif Mongo. SQLite ne le supporte pas correctement (le SQL ne mappe pas
+# l'expression `'$customerId'` vers une référence de colonne).
+DB_DIALECT=mongodb
+SGBD_URI=mongodb://devuser:devpass26@[::1]:27017/sample-08-aggregate?authSource=admin
+
+# Mongo local sans auth (si vous avez votre propre instance) :
+# SGBD_URI=mongodb://127.0.0.1:27017/sample-08-aggregate
+
+# MongoDB Atlas cluster :
+# SGBD_URI=mongodb+srv://USER:PASS@CLUSTER.mongodb.net/sample-08-aggregate

package/examples/08-aggregate-pipeline/08-aggregate-pipeline.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")"
+
+if [ ! -d node_modules ]; then
+  echo "─── Installing dependencies (first run) ───"
+  npm install --silent --no-audit --no-fund
+fi
+
+rm -f app.db
+npx -y tsx app.ts

package/examples/08-aggregate-pipeline/README.md

@@ -0,0 +1,74 @@
+# 08-aggregate-pipeline
+
+> Pipeline d'agrégation MongoDB-style — `$match` + `$group` + `$sort` + `$limit` avec accumulators `$sum`/`$avg`/`$count`.
+
+**Couvre** : `aggregate`, `AggregateStage`, `AggregateGroupStage`,
+`AggregateMatchStage`, `AggregateSortStage`, `AggregateLimitStage`,
+`AggregateAccumulator`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/08-aggregate-pipeline ~/my-aggregate-app
+cd ~/my-aggregate-app
+rm -rf ../tmp
+```
+
+## External resources
+
+**MongoDB requis** *(pas SQLite)* — le pipeline `$match/$group/$sort/$limit`
+est natif Mongo. SQLite ne mappe pas correctement l'expression `'$customerId'`
+vers une référence de colonne.
+
+```bash
+# Local (sans auth, instance déjà tournante) :
+# Cf. .env.example pour les variantes.
+
+# OR : docker
+docker run -d -p 27017:27017 --name mongo mongo:7
+
+# OR : MongoDB Atlas cloud cluster (cf. .env.example)
+```
+
+Le `.env.example` fourni utilise par défaut une instance Mongo accessible
+en `[::1]:27017` avec credentials `devuser/devpass26?authSource=admin`.
+Adapter selon votre environnement.
+
+## Run
+
+```bash
+./08-aggregate-pipeline.sh
+```
+
+## Expected output
+
+```
+─── Aggregate pipeline — @mostajs/orm ───
+✓ seeded 15 orders across 3 customers, statuses [completed,pending,cancelled]
+─── Pipeline : top 3 customers par CA (completed only) ───
+  - cust-c   total=  4500  count= 3
+  - cust-a   total=  3000  count= 2
+  - cust-b   total=  1500  count= 1
+✓ 3 résultats triés desc
+─── Pipeline : count par status ───
+  - completed   6
+  - pending     5
+  - cancelled   4
+✓ chaque status agrégé
+✅ Smoke OK — pipeline aggregate démontré.
+```
+
+## What it shows
+
+- `$match` : filtrage initial avant agrégation
+- `$group` avec `_id` = clé de groupement et accumulators `$sum`, `$count`
+- `$sort` : tri des résultats agrégés
+- `$limit` : top-N
+
+## Files
+
+- `app.ts` — 2 pipelines distincts (top-N + count par status)
+- `schemas/order.schema.ts` — Order avec customerId, status, amount
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/08-aggregate-pipeline/app.ts

@@ -0,0 +1,95 @@
+// Aggregate pipeline — $match + $group + $sort + $limit (MongoDB native).
+//
+// Démontre :
+//   - aggregate() avec un AggregateStage[]
+//   - AggregateMatchStage   : { $match: filter }
+//   - AggregateGroupStage   : { $group: { _id: ..., field: accumulator } }
+//   - AggregateAccumulator  : { $sum: 1 | '$field' }
+//   - AggregateSortStage    : { $sort: { field: -1 } }
+//   - AggregateLimitStage   : { $limit: N }
+//
+// Pourquoi MongoDB ici : le pipeline $match/$group/$sort/$limit est NATIF
+// Mongo. SQLite ne mappe pas correctement l'expression '$customerId' vers
+// une référence de colonne. Pour les dialects SQL, utiliser GROUP BY direct
+// via $raw n'est pas encore standardisé — `aggregate()` reste optimal sur
+// MongoDB en V1.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import { createConnection, BaseRepository } from '@mostajs/orm'
+import { OrderSchema, type OrderRow } from './schemas/order.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── Aggregate pipeline (MongoDB) — @mostajs/orm ───')
+
+  const uri = process.env.SGBD_URI
+    ?? 'mongodb://devuser:devpass26@[::1]:27017/sample-08-aggregate?authSource=admin'
+
+  const dialect = await createConnection(
+    { dialect: 'mongodb', uri, schemaStrategy: 'update' },
+    [OrderSchema],
+  )
+  const orders = new BaseRepository<OrderRow>(OrderSchema, dialect)
+
+  // Reset collection en mongo (équivalent du DROP TABLE en SQL).
+  await orders.deleteMany({})
+
+  // ── Seed : 15 commandes sur 3 clients × 3 statuses ──────────
+  const data: Array<Partial<OrderRow>> = [
+    { customerId: 'cust-a', status: 'completed', amount: 1000 },
+    { customerId: 'cust-a', status: 'completed', amount: 2000 },
+    { customerId: 'cust-a', status: 'pending',   amount:  500 },
+    { customerId: 'cust-a', status: 'cancelled', amount:  300 },
+    { customerId: 'cust-b', status: 'completed', amount: 1500 },
+    { customerId: 'cust-b', status: 'pending',   amount:  700 },
+    { customerId: 'cust-b', status: 'pending',   amount:  400 },
+    { customerId: 'cust-b', status: 'cancelled', amount:  200 },
+    { customerId: 'cust-c', status: 'completed', amount: 1500 },
+    { customerId: 'cust-c', status: 'completed', amount: 1500 },
+    { customerId: 'cust-c', status: 'completed', amount: 1500 },
+    { customerId: 'cust-c', status: 'pending',   amount:  800 },
+    { customerId: 'cust-c', status: 'pending',   amount:  600 },
+    { customerId: 'cust-c', status: 'cancelled', amount:  100 },
+    { customerId: 'cust-c', status: 'cancelled', amount:  100 },
+  ]
+  for (const d of data) await orders.create(d)
+  console.log('✓ seeded 15 orders across 3 customers, statuses [completed,pending,cancelled]')
+
+  // ── Pipeline 1 : top-N clients par CA (completed only) ──────
+  console.log('─── Pipeline : top 3 customers par CA (completed only) ───')
+  const topCustomers = await orders.aggregate([
+    { $match: { status: 'completed' } },
+    { $group: { _id: '$customerId', total: { $sum: '$amount' }, count: { $sum: 1 } } },
+    { $sort: { total: -1 } },
+    { $limit: 3 },
+  ])
+  for (const row of topCustomers) {
+    console.log(`  - ${String(row._id).padEnd(8)} total=${String(row.total).padStart(6)}  count=${String(row.count).padStart(2)}`)
+  }
+  console.log(`✓ ${topCustomers.length} résultats triés desc`)
+  if (topCustomers.length !== 3) throw new Error(`expected 3 top customers, got ${topCustomers.length}`)
+  if (topCustomers[0]._id !== 'cust-c') throw new Error(`expected cust-c first, got ${topCustomers[0]._id}`)
+
+  // ── Pipeline 2 : count par status (sans $match) ─────────────
+  console.log('─── Pipeline : count par status ───')
+  const byStatus = await orders.aggregate([
+    { $group: { _id: '$status', count: { $sum: 1 } } },
+    { $sort: { count: -1 } },
+  ])
+  for (const row of byStatus) {
+    console.log(`  - ${String(row._id).padEnd(12)} ${row.count}`)
+  }
+  console.log('✓ chaque status agrégé')
+  if (byStatus.length !== 3) throw new Error(`expected 3 status groups, got ${byStatus.length}`)
+
+  console.log('✅ Smoke OK — pipeline aggregate démontré sur MongoDB.')
+
+  // Cleanup
+  await orders.deleteMany({})
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/08-aggregate-pipeline/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "08-aggregate-pipeline",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "mongoose": "^8.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/08-aggregate-pipeline/schemas/order.schema.ts

@@ -0,0 +1,28 @@
+// Schéma Order pour agrégation : customerId + status + amount.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import type { EntitySchema } from '@mostajs/orm'
+
+export const OrderSchema: EntitySchema = {
+  name: 'Order',
+  collection: 'orders',
+  fields: {
+    customerId: { type: 'string', required: true },
+    status:     { type: 'string', enum: ['completed', 'pending', 'cancelled'], required: true },
+    amount:     { type: 'number', required: true },
+  },
+  relations: {},
+  indexes: [
+    { fields: { customerId: 'asc' } },
+    { fields: { status: 'asc' } },
+  ],
+  timestamps: true,
+}
+
+export interface OrderRow {
+  id: string
+  customerId: string
+  status: 'completed' | 'pending' | 'cancelled'
+  amount: number
+  createdAt?: Date
+}

package/examples/09-findbyid-polymorphic/.env.example

@@ -0,0 +1,2 @@
+DB_DIALECT=sqlite
+SGBD_URI=./app.db

package/examples/09-findbyid-polymorphic/09-findbyid-polymorphic.sh

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+set -e
+cd "$(dirname "$0")"
+
+if [ ! -d node_modules ]; then
+  echo "─── Installing dependencies (first run) ───"
+  npm install --silent --no-audit --no-fund
+fi
+
+rm -f app.db
+npx -y tsx app.ts

package/examples/09-findbyid-polymorphic/README.md

@@ -0,0 +1,65 @@
+# 09-findbyid-polymorphic
+
+> Les 4 formes de `findById()` (string / `{id}` / natural key single / composite) + `extractRelId` + `OrmIntrospectionError`. La vitrine de la 2.0.
+
+**Couvre** : `findById` (4 formes), `resolveLookup`, `findMatchingUniqueIndex`,
+`UniqueIndexMatch`, `ResolvedLookup`, `OrmIntrospectionError`,
+`extractRelId`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/09-findbyid-polymorphic ~/my-polymorphic-app
+cd ~/my-polymorphic-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune *(SQLite via better-sqlite3)*.
+
+## Run
+
+```bash
+./09-findbyid-polymorphic.sh
+```
+
+## Expected output
+
+```
+─── findById polymorphique + extractRelId — @mostajs/orm ───
+✓ seeded : Project 'orphin' + Membership (admin sur Project 'orphin')
+─── Forme 1 : findById('id-string')
+   → Project name='orphin'
+─── Forme 2 : findById({ id: '…' })
+   → Project name='orphin'
+─── Forme 3 : findById({ slug }) — natural key single
+   → Project name='orphin' via unique index { slug }
+─── Forme 4 : findById({ projectId, role }) — composite natural key
+   → Membership found via unique index { projectId+role }
+─── Erreur typée : findById({ unknown: 'foo' })
+   → OrmIntrospectionError schema='Project' availableFields=[unknown]
+─── Helper extractRelId
+   extractRelId('abc')                 = 'abc'
+   extractRelId({ id: 'abc' })         = 'abc'
+   extractRelId(null)                  = ''
+   extractRelId({ slug: 'foo' })       = ''  (pas d'id direct)
+✅ Smoke OK — 4 formes findById + extractRelId + error typing.
+```
+
+## What it shows
+
+- **Forme 1** : compatible legacy (string PK comme avant 2.0)
+- **Forme 2** : pratique quand le caller a un objet populé en main
+- **Forme 3** : natural key — l'introspection résout via `unique` index
+- **Forme 4** : composite — `{tenantId, slug}` etc. via index unique composite
+- **Erreur actionnable** : `OrmIntrospectionError` liste les fields disponibles + unique indexes candidats
+- **`extractRelId`** : helper pour comparaisons sûres en lazy ET eager
+
+## Files
+
+- `app.ts` — 4 formes + extractRelId + erreur typée
+- `schemas/` — Project (avec unique slug) + Membership (composite unique)
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/09-findbyid-polymorphic/app.ts

@@ -0,0 +1,97 @@
+// findById polymorphique — 4 formes + extractRelId + OrmIntrospectionError.
+//
+// Démontre :
+//   Forme 1 : findById('id-string')                — PK direct (legacy)
+//   Forme 2 : findById({ id: '...' })              — objet contenant id
+//   Forme 3 : findById({ slug: '...' })            — natural key single
+//   Forme 4 : findById({ projectId, role })        — composite natural key
+//   Erreur  : findById({ unknown: 'foo' })         — OrmIntrospectionError
+//   Helper  : extractRelId(val)                    — normalise vers string id
+//
+// Introspection : resolveLookup + findMatchingUniqueIndex (utilisés en
+// interne par findById). Disponibles publiquement pour debug ou outillage.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import {
+  createConnection,
+  BaseRepository,
+  extractRelId,
+  OrmIntrospectionError,
+  resolveLookup,
+} from '@mostajs/orm'
+import {
+  ProjectSchema, MembershipSchema,
+  type ProjectRow, type MembershipRow,
+} from './schemas/index.js'
+
+async function main(): Promise<void> {
+  console.log('─── findById polymorphique + extractRelId — @mostajs/orm ───')
+
+  const dialect = await createConnection(
+    { dialect: 'sqlite', uri: './app.db', schemaStrategy: 'create' },
+    [ProjectSchema, MembershipSchema],
+  )
+
+  const projects = new BaseRepository<ProjectRow>(ProjectSchema, dialect)
+  const memberships = new BaseRepository<MembershipRow>(MembershipSchema, dialect)
+
+  // ── Seed ────────────────────────────────────────────────────
+  const proj = await projects.create({ slug: 'orphin', name: 'orphin' })
+  await memberships.create({ projectId: proj.id, role: 'admin', userId: 'user-1' })
+  console.log("✓ seeded : Project 'orphin' + Membership (admin sur Project 'orphin')")
+
+  // ── Forme 1 : string PK direct ──────────────────────────────
+  console.log("─── Forme 1 : findById('id-string')")
+  const p1 = await projects.findById(proj.id)
+  console.log(`   → Project name='${p1?.name}'`)
+  if (!p1) throw new Error('Forme 1 failed')
+
+  // ── Forme 2 : objet avec id (cas d'une relation populée) ────
+  console.log("─── Forme 2 : findById({ id: '…' })")
+  const p2 = await projects.findById({ id: proj.id })
+  console.log(`   → Project name='${p2?.name}'`)
+  if (!p2 || p2.id !== proj.id) throw new Error('Forme 2 failed')
+
+  // ── Forme 3 : natural key single (slug unique) ──────────────
+  console.log("─── Forme 3 : findById({ slug }) — natural key single")
+  const p3 = await projects.findById({ slug: 'orphin' })
+  console.log(`   → Project name='${p3?.name}' via unique index { slug }`)
+  if (!p3 || p3.id !== proj.id) throw new Error('Forme 3 failed')
+
+  // ── Forme 4 : composite natural key ─────────────────────────
+  console.log("─── Forme 4 : findById({ projectId, role }) — composite natural key")
+  const m4 = await memberships.findById({ projectId: proj.id, role: 'admin' })
+  console.log(`   → Membership found via unique index { projectId+role }`)
+  if (!m4) throw new Error('Forme 4 failed')
+
+  // ── Erreur typée : ni id ni unique index matching ───────────
+  console.log("─── Erreur typée : findById({ unknown: 'foo' })")
+  try {
+    await projects.findById({ unknown: 'foo' })
+    throw new Error('Expected OrmIntrospectionError, none thrown')
+  } catch (e) {
+    if (!(e instanceof OrmIntrospectionError)) throw e
+    console.log(`   → OrmIntrospectionError schema='${e.schemaName}' availableFields=[${e.availableFields.join(', ')}]`)
+  }
+
+  // ── extractRelId helper ─────────────────────────────────────
+  console.log("─── Helper extractRelId")
+  console.log(`   extractRelId('abc')                 = '${extractRelId('abc')}'`)
+  console.log(`   extractRelId({ id: 'abc' })         = '${extractRelId({ id: 'abc' })}'`)
+  console.log(`   extractRelId(null)                  = '${extractRelId(null)}'`)
+  console.log(`   extractRelId({ slug: 'foo' })       = '${extractRelId({ slug: 'foo' })}'  (pas d'id direct)`)
+
+  // ── Bonus : resolveLookup public pour debug/outillage ───────
+  const resolved = resolveLookup(ProjectSchema, { slug: 'orphin' })
+  if (resolved.kind !== 'natural') throw new Error(`expected kind 'natural', got '${resolved.kind}'`)
+
+  console.log('✅ Smoke OK — 4 formes findById + extractRelId + error typing.')
+
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/09-findbyid-polymorphic/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "09-findbyid-polymorphic",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "better-sqlite3": "^12.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/09-findbyid-polymorphic/schemas/index.ts

@@ -0,0 +1,45 @@
+// Project : unique index sur slug → findById({ slug }) résout.
+// Membership : unique index composite (projectId + role) → findById({ projectId, role }) résout.
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import type { EntitySchema } from '@mostajs/orm'
+
+export const ProjectSchema: EntitySchema = {
+  name: 'Project',
+  collection: 'projects',
+  fields: {
+    slug: { type: 'string', required: true, unique: true },
+    name: { type: 'string', required: true },
+  },
+  relations: {},
+  // Index unique single — exploité par findById({ slug }).
+  indexes: [{ fields: { slug: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export const MembershipSchema: EntitySchema = {
+  name: 'Membership',
+  collection: 'memberships',
+  fields: {
+    projectId: { type: 'string', required: true },
+    role:      { type: 'string', enum: ['admin', 'editor', 'viewer'], required: true },
+    userId:    { type: 'string', required: true },
+  },
+  relations: {},
+  // Index unique composite — exploité par findById({ projectId, role }).
+  indexes: [{ fields: { projectId: 'asc', role: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export interface ProjectRow {
+  id: string
+  slug: string
+  name: string
+}
+
+export interface MembershipRow {
+  id: string
+  projectId: string
+  role: 'admin' | 'editor' | 'viewer'
+  userId: string
+}

package/llms.txt

@@ -1,8 +1,8 @@
 # @mostajs/orm-samples — fiche LLM
 > Runnable samples covering 100% of @mostajs/orm's public API. Copy-paste install per feature.
 
-- Version: 0.1.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
-- Chemin: mostajs/mosta-orm-samples · Statut: Lot 1 livré (samples 01-05)
+- Version: 0.2.0 · Licence: AGPL-3.0-or-later · Auteur: Dr Hamid MADANI <drmdh@msn.com>
+- Chemin: mostajs/mosta-orm-samples · Statut: Lots 1 & 2 livrés (samples 01-09)
 
 ## RÔLE
 Pour chaque export documenté dans le llms.txt de @mostajs/orm, ce module fournit
@@ -30,8 +30,13 @@ npx @mostajs/orm-samples scaffold <feature> [dest]
 - 04-schema-registry : registerSchema + registerSchemas + getSchema + getSchemaByCollection + getAllSchemas + getEntityNames + hasSchema + validateSchemas + clearRegistry
 - 05-types-cles-entity-schema : EntitySchema exhaustif + FieldType (string/text/number/boolean/date/json/array) + FieldDef (required/unique/sparse/default/enum/lowercase/trim/arrayOf) + IndexDef + IndexType + softDelete + discriminator + timestamps
 
-## SAMPLES À VENIR — Lots 2-5
-- Lot 2 (CRUD & queries) : findById polymorphique, FilterOperator complet, aggregate pipeline
+## SAMPLES LIVRÉS — Lot 2 (CRUD & queries)
+- 06-base-repository-crud : 15 méthodes BaseRepository (findAll/findOne/findById/create/update/updateMany/delete/deleteMany/count/distinct/search/upsert/increment/addToSet/pull)
+- 07-filter-query-mongodb-like : 12 opérateurs FilterOperator ($eq/$ne/$gt/$gte/$lt/$lte/$in/$nin/$regex/$exists/$or/$and) + QueryOptions (sort/skip/limit/select) + SortDirection
+- 08-aggregate-pipeline : aggregate + AggregateStage + $match/$group/$sort/$limit + AggregateAccumulator (MongoDB requis — pipeline natif Mongo, SQL non supporté pour $group avec expression $field)
+- 09-findbyid-polymorphic : findById 4 formes (string/{id}/natural key/composite) + resolveLookup + UniqueIndexMatch + ResolvedLookup + OrmIntrospectionError (avec schemaName/availableFields) + extractRelId
+
+## SAMPLES À VENIR — Lots 3-5
 - Lot 3 (Relations & lifecycle) : RelationDef + lazy/eager + migration + soft-delete + audit + tx
 - Lot 4 (Plugins & sous-modules) : IPlugin + /register + /bridge JDBC
 - Lot 5 (Validator & erreurs) : validator + auto-fix + erreurs + EntityService + config + lifecycle

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mostajs/orm-samples",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Runnable samples covering 100% of @mostajs/orm's llms.txt — copy-paste install per feature.",
   "author": "Dr Hamid MADANI <drmdh@msn.com>",
   "license": "AGPL-3.0-or-later",
@@ -58,5 +58,8 @@
   "funding": {
     "type": "github",
     "url": "https://github.com/sponsors/apolocine"
+  },
+  "dependencies": {
+    "mongoose": "^9.6.2"
   }
 }