@mostajs/orm-samples 0.1.0

package/examples/02-multi-dialect-switch/app.ts

@@ -0,0 +1,68 @@
+// Multi-dialect switch — un seul code, plusieurs SGBD via .env.
+//
+// Démontre :
+//   - getSupportedDialects() : énumération des dialects supportés
+//   - getDialectConfig(name) : métadata d'un dialect (driver, etc.)
+//   - getConfigFromEnv() : lit DB_DIALECT + SGBD_URI depuis .env
+//   - createConnection(config) : config-driven, dialect-agnostic
+//   - getCurrentDialectType() : type du dialect actuellement connecté
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import {
+  createConnection,
+  getConfigFromEnv,
+  getSupportedDialects,
+  getDialectConfig,
+  getCurrentDialectType,
+  BaseRepository,
+} from '@mostajs/orm'
+import { UserSchema, type UserRow } from './schemas/user.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── Multi-dialect switch — @mostajs/orm ───')
+
+  // 1. Liste exhaustive des dialects supportés par la version installée.
+  console.log('\nDialects supportés :')
+  for (const name of getSupportedDialects()) {
+    const cfg = getDialectConfig(name)
+    console.log(`  - ${name.padEnd(12)} ${cfg?.label ?? cfg?.driver ?? ''}`)
+  }
+
+  // 2. Config lue depuis .env (DB_DIALECT + SGBD_URI). Si rien n'est défini,
+  // on fournit un fallback sqlite local — utile pour la première exécution
+  // sans configurer .env.
+  let config
+  try {
+    config = getConfigFromEnv()
+  } catch {
+    console.log('\nℹ DB_DIALECT non défini — fallback SQLite local.')
+    config = { dialect: 'sqlite' as const, uri: './app.db' }
+  }
+  config.schemaStrategy = 'update'
+
+  console.log('\n✓ Config courante :', config)
+
+  // 3. Connexion sur le dialect choisi.
+  const dialect = await createConnection(config, [UserSchema])
+  const currentDialect = getCurrentDialectType()
+  console.log(`✓ Connecté à : ${currentDialect}`)
+
+  // 4. Le code applicatif est strictement le même quel que soit le SGBD.
+  const users = new BaseRepository<UserRow>(UserSchema, dialect)
+  const email = `multi-${currentDialect}-${Date.now()}@example.com`
+  const created = await users.create({ email, name: 'MultiDialect' })
+  console.log(`✓ User créé sur ${currentDialect} (id=${created.id})`)
+
+  const found = await users.findOne({ email })
+  if (!found) throw new Error('findOne failed after create')
+
+  console.log('✅ Smoke OK — le même code marche sur n\'importe quel dialect.')
+
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/02-multi-dialect-switch/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "02-multi-dialect-switch",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "better-sqlite3": "^12.0.0"
+  },
+  "optionalDependencies": {
+    "pg": "^8.20.0",
+    "mysql2": "^3.0.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/02-multi-dialect-switch/schemas/user.schema.ts

@@ -0,0 +1,25 @@
+// Schéma User identique au sample 01 — la portabilité dialect repose sur
+// le fait que le SAME EntitySchema fonctionne pour tous les dialects SQL.
+// 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' },
+  },
+  relations: {},
+  indexes: [{ fields: { email: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export interface UserRow {
+  id: string
+  email: string
+  name?: string
+  createdAt?: Date
+  updatedAt?: Date
+}

package/examples/03-isolated-connections/.env.example

@@ -0,0 +1,2 @@
+# Ce sample utilise des paths SQLite codés en dur (tenant-a.db, tenant-b.db).
+# Pour adapter à d'autres dialects, modifier directement app.ts.

package/examples/03-isolated-connections/03-isolated-connections.sh

@@ -0,0 +1,12 @@
+#!/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 tenant-a.db tenant-b.db
+
+npx -y tsx app.ts

package/examples/03-isolated-connections/README.md

@@ -0,0 +1,56 @@
+# 03-isolated-connections
+
+> Multi-tenant via `createIsolatedDialect` + connexions nommées — démontre la différence entre singleton `getDialect()` et instances isolées.
+
+**Couvre** : `createIsolatedDialect`, `getDialect` (piège singleton),
+`registerNamedConnection`, `getNamedConnection`, `removeNamedConnection`,
+`listNamedConnections`, `clearNamedConnections`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/03-isolated-connections ~/my-isolated-app
+cd ~/my-isolated-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune *(SQLite via better-sqlite3)*.
+
+## Run
+
+```bash
+./03-isolated-connections.sh
+```
+
+## Expected output
+
+```
+─── Isolated connections — @mostajs/orm ───
+✓ tenant-a connecté à ./tenant-a.db
+✓ tenant-b connecté à ./tenant-b.db
+✓ named connections enregistrées : tenant-a, tenant-b
+✓ count tenant-a = 1
+✓ count tenant-b = 2
+✓ DBs physiquement distinctes (count diffère)
+✅ Smoke OK
+```
+
+## What it shows
+
+- **Piège singleton** : `getDialect()` retourne **toujours la même
+  instance**. Pour deux tenants, utiliser `createIsolatedDialect()` qui
+  bypass le singleton.
+- **Named connections** : registre clé→dialect pour récupérer une
+  connexion par nom métier sans la passer en paramètre partout.
+- **Lifecycle complet** : register → use → unregister → clear.
+
+## Files
+
+- `app.ts` — main code multi-tenant
+- `schemas/user.schema.ts` — schéma partagé entre les 2 tenants
+- `.env.example` — config
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/03-isolated-connections/app.ts

@@ -0,0 +1,79 @@
+// Isolated connections — multi-tenant via createIsolatedDialect + named connections.
+//
+// Démontre :
+//   - Piège getDialect() singleton vs createIsolatedDialect()
+//   - registerNamedConnection / getNamedConnection / listNamedConnections /
+//     removeNamedConnection / clearNamedConnections
+//
+// Cas d'usage : SaaS multi-tenant où chaque client a sa propre DB.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import {
+  createIsolatedDialect,
+  registerNamedConnection,
+  getNamedConnection,
+  listNamedConnections,
+  removeNamedConnection,
+  clearNamedConnections,
+  BaseRepository,
+} from '@mostajs/orm'
+import { UserSchema, type UserRow } from './schemas/user.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── Isolated connections — @mostajs/orm ───')
+
+  // 1. Deux tenants = deux DB physiquement séparées. createIsolatedDialect
+  //    bypass le singleton interne — chaque appel retourne une instance neuve.
+  const dialectA = await createIsolatedDialect(
+    { dialect: 'sqlite', uri: './tenant-a.db', schemaStrategy: 'update' },
+    [UserSchema],
+  )
+  console.log('✓ tenant-a connecté à ./tenant-a.db')
+
+  const dialectB = await createIsolatedDialect(
+    { dialect: 'sqlite', uri: './tenant-b.db', schemaStrategy: 'update' },
+    [UserSchema],
+  )
+  console.log('✓ tenant-b connecté à ./tenant-b.db')
+
+  // 2. Registre nommé pour récupérer une connexion par nom métier.
+  registerNamedConnection('tenant-a', dialectA)
+  registerNamedConnection('tenant-b', dialectB)
+  console.log('✓ named connections enregistrées :', listNamedConnections().join(', '))
+
+  // 3. Repositories tirés depuis les named connections.
+  const repoA = new BaseRepository<UserRow>(UserSchema, getNamedConnection('tenant-a')!)
+  const repoB = new BaseRepository<UserRow>(UserSchema, getNamedConnection('tenant-b')!)
+
+  // 4. Données différentes par tenant — preuve d'isolement.
+  await repoA.create({ email: `a-${Date.now()}@tenant-a.example.com`, name: 'Alice A' })
+  await repoB.create({ email: `b1-${Date.now()}@tenant-b.example.com`, name: 'Bob B1' })
+  await repoB.create({ email: `b2-${Date.now()}@tenant-b.example.com`, name: 'Bob B2' })
+
+  const countA = await repoA.count({})
+  const countB = await repoB.count({})
+  console.log(`✓ count tenant-a = ${countA}`)
+  console.log(`✓ count tenant-b = ${countB}`)
+
+  if (countA !== 1 || countB !== 2) {
+    throw new Error(`isolation assertion failed: A=${countA}, B=${countB} (expected 1, 2)`)
+  }
+  console.log('✓ DBs physiquement distinctes (count diffère)')
+
+  // 5. Cleanup — removeNamedConnection puis clearNamedConnections.
+  removeNamedConnection('tenant-a')
+  console.log(`✓ après remove tenant-a : ${listNamedConnections().join(', ') || '(vide)'}`)
+  clearNamedConnections()
+  console.log(`✓ après clearAll : ${listNamedConnections().length} connexions`)
+
+  console.log('✅ Smoke OK')
+
+  await dialectA.disconnect?.()
+  await dialectB.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/03-isolated-connections/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "03-isolated-connections",
+  "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/03-isolated-connections/schemas/user.schema.ts

@@ -0,0 +1,23 @@
+// Schéma User partagé entre les tenants — la séparation est au niveau
+// DB physique, pas au niveau schéma.
+// 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' },
+  },
+  relations: {},
+  indexes: [{ fields: { email: 'asc' }, unique: true }],
+  timestamps: true,
+}
+
+export interface UserRow {
+  id: string
+  email: string
+  name?: string
+}

package/examples/04-schema-registry/.env.example

@@ -0,0 +1,2 @@
+# Ce sample n'utilise PAS de dialect — le registre est purement en mémoire.
+# Aucune variable d'environnement requise.

package/examples/04-schema-registry/04-schema-registry.sh

@@ -0,0 +1,10 @@
+#!/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
+
+npx -y tsx app.ts

package/examples/04-schema-registry/README.md

@@ -0,0 +1,56 @@
+# 04-schema-registry
+
+> Registre global de schémas : register / lookup / validate / clear, indépendant du dialect.
+
+**Couvre** : `registerSchema`, `registerSchemas`, `getSchema`,
+`getSchemaByCollection`, `getAllSchemas`, `getEntityNames`, `hasSchema`,
+`validateSchemas`, `clearRegistry`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/04-schema-registry ~/my-registry-app
+cd ~/my-registry-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune.
+
+## Run
+
+```bash
+./04-schema-registry.sh
+```
+
+## Expected output
+
+```
+─── Schema registry — @mostajs/orm ───
+✓ 3 schémas enregistrés en batch : User, Project, Registration
+✓ getEntityNames() = [ 'User', 'Project', 'Registration' ]
+✓ hasSchema('User') = true
+✓ getSchema('User').collection = 'users'
+✓ getSchemaByCollection('projects').name = 'Project'
+✓ validateSchemas() = { valid: true, errors: [] }
+✓ clearRegistry() → 0 schémas restants
+✓ ré-registerSchema('Tag') → hasSchema('Tag') = true
+✅ Smoke OK
+```
+
+## What it shows
+
+- `registerSchemas([…])` (batch) vs `registerSchema(s)` (single)
+- 3 lookups : par nom, par collection, all
+- `validateSchemas()` vérifie que les cibles de relations existent dans le registre
+- Cycle complet : register → use → clear → re-register
+
+## Files
+
+- `app.ts` — main code
+- `schemas/` — 3 schémas (User, Project, Registration) avec relations
+- `.env.example` — N/A (pas de DB pour ce sample)
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>

package/examples/04-schema-registry/app.ts

@@ -0,0 +1,78 @@
+// Schema registry — registre global indépendant du dialect.
+//
+// Démontre :
+//   - registerSchema(s) / registerSchemas([…])
+//   - getSchema, getSchemaByCollection, getAllSchemas, getEntityNames, hasSchema
+//   - validateSchemas (vérifie les cibles de relations)
+//   - clearRegistry + cycle de re-registration
+//
+// Pas besoin de connexion DB : le registre est purement en mémoire et
+// peut être utilisé pour de l'introspection avant tout dialect.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import {
+  registerSchema,
+  registerSchemas,
+  getSchema,
+  getSchemaByCollection,
+  getAllSchemas,
+  getEntityNames,
+  hasSchema,
+  validateSchemas,
+  clearRegistry,
+} from '@mostajs/orm'
+import { UserSchema, ProjectSchema, RegistrationSchema, TagSchema } from './schemas/index.js'
+
+async function main(): Promise<void> {
+  console.log('─── Schema registry — @mostajs/orm ───')
+
+  // Bonne pratique : clear avant en cas de re-run dans la même process.
+  clearRegistry()
+
+  // 1. registerSchemas — batch.
+  registerSchemas([UserSchema, ProjectSchema, RegistrationSchema])
+  const names = getEntityNames()
+  console.log(`✓ 3 schémas enregistrés en batch : ${names.join(', ')}`)
+
+  if (names.length !== 3) throw new Error(`expected 3 schemas, got ${names.length}`)
+
+  // 2. getEntityNames — liste des noms enregistrés.
+  console.log('✓ getEntityNames() =', names)
+
+  // 3. hasSchema — check d'existence.
+  console.log(`✓ hasSchema('User') = ${hasSchema('User')}`)
+  if (!hasSchema('User')) throw new Error('User missing')
+
+  // 4. getSchema — lookup par nom (throw si absent).
+  console.log(`✓ getSchema('User').collection = '${getSchema('User').collection}'`)
+
+  // 5. getSchemaByCollection — lookup par table/collection name.
+  const byColl = getSchemaByCollection('projects')
+  console.log(`✓ getSchemaByCollection('projects').name = '${byColl?.name}'`)
+
+  // 6. getAllSchemas — récupère tous les schémas pour iteration.
+  const all = getAllSchemas()
+  if (all.length !== 3) throw new Error(`getAllSchemas count mismatch: ${all.length}`)
+
+  // 7. validateSchemas — vérifie que les `target` des relations existent.
+  const validation = validateSchemas()
+  console.log('✓ validateSchemas() =', validation)
+  if (!validation.valid) throw new Error(`validation failed: ${validation.errors.join(', ')}`)
+
+  // 8. clearRegistry — vide tout. Utile en tests, dans les hot-reload, etc.
+  clearRegistry()
+  console.log(`✓ clearRegistry() → ${getEntityNames().length} schémas restants`)
+  if (getEntityNames().length !== 0) throw new Error('clearRegistry failed')
+
+  // 9. registerSchema unitaire — alternative au batch.
+  registerSchema(TagSchema)
+  console.log(`✓ ré-registerSchema('Tag') → hasSchema('Tag') = ${hasSchema('Tag')}`)
+
+  console.log('✅ Smoke OK')
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

package/examples/04-schema-registry/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "04-schema-registry",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "tsx app.ts"
+  },
+  "dependencies": {
+    "@mostajs/orm": "^2.1.0"
+  },
+  "devDependencies": {
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/examples/04-schema-registry/schemas/index.ts

@@ -0,0 +1,35 @@
+// 3 schémas avec relations croisées pour démontrer validateSchemas() :
+// User ← Project (many-to-one author) ← Registration (many-to-one project).
+// 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 } },
+  relations: {}, indexes: [], timestamps: true,
+}
+
+export const ProjectSchema: EntitySchema = {
+  name: 'Project', collection: 'projects',
+  fields: { name: { type: 'string', required: true } },
+  relations: {
+    author: { type: 'many-to-one', target: 'User', onDelete: 'set-null' },
+  },
+  indexes: [], timestamps: true,
+}
+
+export const RegistrationSchema: EntitySchema = {
+  name: 'Registration', collection: 'registrations',
+  fields: { code: { type: 'string', required: true } },
+  relations: {
+    project: { type: 'many-to-one', target: 'Project', onDelete: 'cascade' },
+  },
+  indexes: [], timestamps: true,
+}
+
+export const TagSchema: EntitySchema = {
+  name: 'Tag', collection: 'tags',
+  fields: { label: { type: 'string', required: true, unique: true } },
+  relations: {}, indexes: [], timestamps: true,
+}

package/examples/05-types-cles-entity-schema/.env.example

@@ -0,0 +1,7 @@
+# Default — SQLite local, zéro install externe.
+DB_DIALECT=sqlite
+SGBD_URI=./app.db
+
+# Note : ce sample illustre les TYPES de field/index ; le dialect importe
+# peu car la définition est portable. Sur Postgres/MySQL les types SQL
+# précis (TEXT vs VARCHAR, JSONB vs JSON…) diffèrent automatiquement.

package/examples/05-types-cles-entity-schema/05-types-cles-entity-schema.sh

@@ -0,0 +1,12 @@
+#!/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/05-types-cles-entity-schema/README.md

@@ -0,0 +1,60 @@
+# 05-types-cles-entity-schema
+
+> Tous les types-clés EntitySchema démontrés : chaque FieldType, chaque FieldDef option, IndexDef, discriminator, softDelete.
+
+**Couvre** : `EntitySchema` exhaustif, `FieldDef` *(required, unique, sparse,
+default, enum, lowercase, trim, arrayOf)*, `FieldType`
+*(string, text, number, boolean, date, json, array)*, `EmbeddedSchemaDef`,
+`IndexDef`, `IndexType` *(asc, desc, text)*, `discriminator`,
+`discriminatorValue`, `softDelete`, `timestamps`.
+
+## Install
+
+```bash
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+cp -r node_modules/@mostajs/orm-samples/examples/05-types-cles-entity-schema ~/my-types-app
+cd ~/my-types-app
+rm -rf ../tmp
+```
+
+## External resources
+
+aucune *(SQLite via better-sqlite3)*.
+
+## Run
+
+```bash
+./05-types-cles-entity-schema.sh
+```
+
+## Expected output
+
+```
+─── Types clés EntitySchema — @mostajs/orm ───
+✓ Schéma Article enregistré (softDelete=true, discriminator='_type')
+✓ FieldType démontrés : string, text, number, boolean, date, json, array
+✓ FieldDef options démontrées : required, unique, default, enum, lowercase, trim, arrayOf
+✓ IndexDef : 4 indexes dont 1 unique+sparse, 1 desc, 1 text, 1 composite
+✓ Article créé avec id=… title='Hello' status='draft' (enum default)
+✓ slug lowercase appliqué : 'hello-world' (input était 'Hello-World')
+✓ tags arrayOf string OK : [ 'one', 'two', 'three' ]
+✓ metadata JSON OK : { meta: 'sample' }
+✓ Soft-delete : count={ active: 0, total: 1 } après delete
+✅ Smoke OK
+```
+
+## What it shows
+
+- Un seul schéma `Article` qui exerce **chaque field type, chaque option
+  FieldDef, chaque type d'index**
+- `discriminator` (single-table inheritance Drupal-style) + `discriminatorValue`
+- `softDelete: true` natif + index `sparse: true` cohérent
+- Validation runtime des transformations : `lowercase`, `trim`, `enum default`
+
+## Files
+
+- `app.ts` — main code avec assertions sur chaque option
+- `schemas/article.schema.ts` — le schéma exhaustif
+- `.env.example` — config SQLite
+
+**Author** : Dr Hamid MADANI <drmdh@msn.com>