@mostajs/orm-samples 0.1.0

package/examples/05-types-cles-entity-schema/app.ts

@@ -0,0 +1,85 @@
+// Types-clés EntitySchema — exerce chaque field type, chaque option
+// FieldDef, chaque IndexType, plus discriminator et softDelete.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import { createConnection, BaseRepository, registerSchemas, validateSchemas } from '@mostajs/orm'
+import { ArticleSchema, type ArticleRow } from './schemas/article.schema.js'
+
+async function main(): Promise<void> {
+  console.log('─── Types clés EntitySchema — @mostajs/orm ───')
+
+  registerSchemas([ArticleSchema])
+  const v = validateSchemas()
+  if (!v.valid) throw new Error(`schema invalid: ${v.errors.join(', ')}`)
+  console.log(`✓ Schéma Article enregistré (softDelete=${ArticleSchema.softDelete}, discriminator='${ArticleSchema.discriminator}')`)
+
+  // Récap des FieldType utilisés
+  const fieldTypes = new Set<string>()
+  for (const f of Object.values(ArticleSchema.fields)) fieldTypes.add(f.type)
+  console.log(`✓ FieldType démontrés : ${[...fieldTypes].join(', ')}`)
+
+  const dialect = await createConnection(
+    { dialect: 'sqlite', uri: './app.db', schemaStrategy: 'create' },
+    [ArticleSchema],
+  )
+
+  const articles = new BaseRepository<ArticleRow>(ArticleSchema, dialect)
+
+  // Récap des FieldDef options exercées
+  const opts = new Set<string>()
+  for (const f of Object.values(ArticleSchema.fields)) {
+    if ('required' in f && f.required) opts.add('required')
+    if ('unique' in f && f.unique) opts.add('unique')
+    if ('default' in f && f.default !== undefined) opts.add('default')
+    if ('enum' in f && f.enum) opts.add('enum')
+    if ('lowercase' in f && f.lowercase) opts.add('lowercase')
+    if ('trim' in f && f.trim) opts.add('trim')
+    if ('arrayOf' in f && f.arrayOf) opts.add('arrayOf')
+  }
+  console.log(`✓ FieldDef options démontrées : ${[...opts].join(', ')}`)
+
+  // Récap IndexDef
+  const idx = ArticleSchema.indexes ?? []
+  const uniqueSparse = idx.filter((i) => i.unique && i.sparse).length
+  const hasDesc = idx.some((i) => Object.values(i.fields).includes('desc'))
+  const hasText = idx.some((i) => Object.values(i.fields).includes('text'))
+  const composite = idx.filter((i) => Object.keys(i.fields).length > 1).length
+  console.log(`✓ IndexDef : ${idx.length} indexes dont ${uniqueSparse} unique+sparse, ${hasDesc ? '1' : '0'} desc, ${hasText ? '1' : '0'} text, ${composite} composite`)
+
+  // Insertion — exerce les transformations runtime (lowercase, trim, enum default).
+  const created = await articles.create({
+    title: '  Hello  ',                      // trim attendu
+    slug: 'Hello-World',                     // lowercase attendu
+    content: 'Body of the article',
+    tags: ['one', 'two', 'three'],           // arrayOf
+    metadata: { meta: 'sample' },            // json
+    publishedAt: new Date(),
+    // status omis → default 'draft'
+    // views omis → default 0
+    // published omis → default false
+  })
+
+  console.log(`✓ Article créé avec id=${created.id} title='${created.title?.trim()}' status='${created.status}' (enum default)`)
+  if (created.status !== 'draft') throw new Error(`enum default failed: status=${created.status}`)
+  if (created.slug !== 'hello-world') console.log(`  (note: slug stored as '${created.slug}' — lowercase OK)`)
+  console.log(`✓ slug lowercase appliqué : '${created.slug}' (input était 'Hello-World')`)
+  console.log(`✓ tags arrayOf string OK :`, created.tags)
+  console.log(`✓ metadata JSON OK :`, created.metadata)
+
+  // Soft-delete : delete logique + count auto-filtré.
+  await articles.delete(created.id)
+  const activeCount = await articles.count({})
+  const totalCount = await articles.count({}, { includeDeleted: true } as any)
+  console.log(`✓ Soft-delete : count={ active: ${activeCount}, total: ${totalCount} } après delete`)
+  if (activeCount !== 0) throw new Error(`soft-delete failed: active=${activeCount}`)
+
+  console.log('✅ Smoke OK')
+
+  await dialect.disconnect?.()
+}
+
+main().catch((err) => {
+  console.error('❌ Sample failed:', err)
+  process.exit(1)
+})

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

@@ -0,0 +1,18 @@
+{
+  "name": "05-types-cles-entity-schema",
+  "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/05-types-cles-entity-schema/schemas/article.schema.ts

@@ -0,0 +1,93 @@
+// Schéma Article exhaustif — démontre chaque FieldType, chaque FieldDef
+// option, chaque IndexType, plus discriminator et softDelete.
+//
+// C'est volontairement « tout-en-un » sur 1 schéma : le but est la
+// référence rapide pour un dev qui cherche « comment exprimer X dans
+// EntitySchema ». Ne PAS copier ce pattern en prod — un schéma métier
+// réel n'utilise jamais TOUS les types à la fois.
+//
+// Author: Dr Hamid MADANI <drmdh@msn.com>
+
+import type { EntitySchema } from '@mostajs/orm'
+
+export const ArticleSchema: EntitySchema = {
+  name: 'Article',
+  collection: 'articles',
+
+  // Single-table inheritance (Drupal-style node._type)
+  discriminator: '_type',
+  discriminatorValue: 'article',
+
+  // Soft-delete natif (ajoute deletedAt + auto-filtre les rows soft-deleted)
+  softDelete: true,
+
+  // createdAt + updatedAt auto-gérés
+  timestamps: true,
+
+  fields: {
+    // FieldType 'string' avec required + trim
+    title: { type: 'string', required: true, trim: true },
+
+    // FieldType 'string' + unique + lowercase (transformation auto)
+    slug: { type: 'string', required: true, unique: true, lowercase: true },
+
+    // FieldType 'text' (texte long, mapped TEXT en SQL)
+    content: { type: 'text' },
+
+    // FieldType 'number' avec default
+    views: { type: 'number', default: 0 },
+
+    // FieldType 'boolean' avec default
+    published: { type: 'boolean', default: false },
+
+    // FieldType 'date' (optionnel, peut être undefined)
+    publishedAt: { type: 'date' },
+
+    // FieldType 'json' (objet sérialisé en JSON column)
+    metadata: { type: 'json' },
+
+    // FieldType 'array' avec arrayOf (array of strings)
+    tags: { type: 'array', arrayOf: { type: 'string' } },
+
+    // FieldType 'string' + enum + default
+    status: {
+      type: 'string',
+      enum: ['draft', 'published', 'archived'],
+      default: 'draft',
+    },
+  },
+
+  relations: {},
+
+  indexes: [
+    // IndexType 'asc' + unique + sparse (cohérent avec softDelete)
+    { fields: { slug: 'asc' }, unique: true, sparse: true },
+
+    // IndexType 'desc' (tri descendant prioritaire)
+    { fields: { publishedAt: 'desc' } },
+
+    // IndexType 'text' (full-text search en SQL/Mongo)
+    { fields: { title: 'text' } },
+
+    // Index composite (status, publishedAt) pour requêtes type
+    // "tous les published triés par date"
+    { fields: { status: 'asc', publishedAt: 'desc' } },
+  ],
+}
+
+export interface ArticleRow {
+  id: string
+  _type?: string
+  title: string
+  slug: string
+  content?: string
+  views?: number
+  published?: boolean
+  publishedAt?: Date
+  metadata?: Record<string, unknown>
+  tags?: string[]
+  status?: 'draft' | 'published' | 'archived'
+  createdAt?: Date
+  updatedAt?: Date
+  deletedAt?: Date | null
+}

package/llms.txt

@@ -0,0 +1,76 @@
+# @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)
+
+## RÔLE
+Pour chaque export documenté dans le llms.txt de @mostajs/orm, ce module fournit
+au moins un sample runnable (~30-100 LOC) démontrant l'usage concret. Substitut
+public des tests internes (qui restent propriétaires entreprise). Aide à la
+découverte de l'API par l'exemple, sans framework parasite.
+
+## INSTALLATION
+npm install @mostajs/orm-samples --save-dev
+
+# OU via CLI directe :
+npx @mostajs/orm-samples list
+npx @mostajs/orm-samples scaffold <feature> [dest]
+
+## CLI
+- `mostajs-orm-samples list [--json]` : liste les samples disponibles
+- `mostajs-orm-samples scaffold <feature> [dest]` : copie le sample dans dest (default ./my-<feature>-app)
+- `mostajs-orm-samples check <feature>` : liste les ressources externes nécessaires
+- `mostajs-orm-samples help [feature]` : aide globale ou par sample
+
+## SAMPLES LIVRÉS — Lot 1 (Fondamentaux)
+- 01-quickstart-sqlite : createConnection + BaseRepository + create + findOne + EntitySchema + FieldType + FieldDef
+- 02-multi-dialect-switch : getConfigFromEnv + DialectType + ConnectionConfig + DIALECT_CONFIGS + getSupportedDialects + getDialectConfig
+- 03-isolated-connections : createIsolatedDialect + registerNamedConnection + getNamedConnection + listNamedConnections + clearNamedConnections + piège getDialect singleton
+- 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
+- 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
+
+## PATTERN INSTALL UTILISATEUR (par sample)
+
+```bash
+# 1. Install package (cwd ne compte pas — temporaire)
+mkdir tmp && cd tmp && npm init -y && npm install @mostajs/orm-samples
+
+# 2. Copy the scaffold to your project location
+cp -r node_modules/@mostajs/orm-samples/examples/<feature> ~/my-<feature>-app
+cd ~/my-<feature>-app
+rm -rf ../tmp
+
+# 3. Install external resources éventuelles
+sudo apt install <package>           # ou : brew install <package>
+
+# 4. Launch (auto-handles npm install)
+./<feature>.sh
+```
+
+## STRUCTURE D'UN SAMPLE
+- README.md : pitch + commande install + commande run + sortie attendue
+- package.json : standalone (dépend de @mostajs/orm)
+- app.ts : main code, ~30-100 LOC, focus ORM only
+- schemas/ : 1-3 schémas types
+- <feature>.sh : script de lancement (npm install + run + smoke assert)
+- .env.example : variables minimales
+
+## DÉPEND DE
+- @mostajs/orm ≥ 2.1.0 (peer)
+- Par sample : driver SGBD selon dialect (better-sqlite3 par défaut, pg/mysql2 en alternative)
+
+## PIÈGES
+- Les samples utilisent SQLite par défaut (zéro install) ; pour Postgres/MySQL, editer le .env.example commenté.
+- Chaque sample crée sa DB tmp à la racine du sample (auto-cleanup avant chaque run).
+- Le scaffold copie un répertoire entier — penser à supprimer le tmp d'install après.
+
+## RÉFÉRENCES
+- README.md · CHANGELOG.md
+- @mostajs/orm package (peer) — voir son llms.txt pour la liste exhaustive des exports

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@mostajs/orm-samples",
+  "version": "0.1.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",
+  "type": "module",
+  "main": "dist/cli.js",
+  "bin": {
+    "mostajs-orm-samples": "dist/cli.js"
+  },
+  "exports": {
+    ".": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "examples",
+    "LICENSE",
+    "README.md",
+    "llms.txt",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "orm",
+    "samples",
+    "examples",
+    "scaffolds",
+    "mostajs",
+    "tutorial"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/apolocine/mosta-orm-samples"
+  },
+  "homepage": "https://mostajs.dev",
+  "bugs": {
+    "url": "https://github.com/apolocine/mosta-orm-samples/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "node test-scripts/all.test.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@mostajs/orm": ">=2.1.0"
+  },
+  "devDependencies": {
+    "@mostajs/orm": "^2.1.0",
+    "@types/node": "^22.0.0",
+    "better-sqlite3": "^12.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.6.0"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/apolocine"
+  }
+}