nestgen-cli 0.0.7 → 0.2.1

package/dist/engine/resource-spec.js

@@ -0,0 +1,287 @@
+const namePattern = /^[a-z][a-z0-9]*$/i;
+const resourceNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/i;
+const enumValuePattern = /^[A-Z][A-Z0-9_]*$/;
+const basicTypes = new Set(['string', 'number', 'integer', 'boolean', 'date', 'uuid']);
+function parseType(rawType, value) {
+    const basicType = rawType.toLowerCase();
+    if (basicTypes.has(basicType))
+        return { type: basicType };
+    const decimal = /^decimal\((\d+);(\d+)\)$/i.exec(rawType);
+    if (decimal) {
+        const precision = Number(decimal[1]);
+        const scale = Number(decimal[2]);
+        if (precision < 1 || precision > 1000 || scale > precision)
+            throw new Error(`Précision décimale invalide : ${value}. La précision doit être entre 1 et 1000, et l'échelle ne peut pas la dépasser.`);
+        return { type: 'decimal', precision, scale };
+    }
+    const enumeration = /^enum\(([^)]+)\)$/i.exec(rawType);
+    if (enumeration) {
+        const enumValues = enumeration[1].split('|');
+        if (enumValues.some((entry) => !enumValuePattern.test(entry)) || new Set(enumValues).size !== enumValues.length)
+            throw new Error(`Enum invalide : ${value}. Les valeurs doivent être uniques, en MAJUSCULES, et séparées par |.`);
+        return { type: 'enum', enumValues };
+    }
+    throw new Error(`Champ invalide : ${value}. Format attendu : nom:type, decimal(précision;échelle) ou enum(VALEUR|VALEUR), avec ? (nullable) ou ! (unique).`);
+}
+function parsePositiveInteger(value, label, field) {
+    if (!/^\d+$/.test(value) || Number(value) < 1)
+        throw new Error(`${label} invalide pour ${field}. Une valeur entière strictement positive est requise.`);
+    return Number(value);
+}
+function parseNumber(value, label, field) {
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed))
+        throw new Error(`${label} invalide pour ${field}. Une valeur numérique finie est requise.`);
+    return parsed;
+}
+function parseDefaultValue(raw, field, value) {
+    if (field.type === 'boolean') {
+        if (raw !== 'true' && raw !== 'false')
+            throw new Error(`Valeur par défaut invalide : ${value}.`);
+        return raw === 'true';
+    }
+    if (field.type === 'integer') {
+        const parsed = parseNumber(raw, 'Valeur par défaut', value);
+        if (!Number.isInteger(parsed))
+            throw new Error(`Valeur par défaut invalide : ${value}. Un entier est requis.`);
+        return parsed;
+    }
+    if (field.type === 'number')
+        return parseNumber(raw, 'Valeur par défaut', value);
+    if (field.type === 'decimal') {
+        if (!/^-?\d+(?:\.\d+)?$/.test(raw))
+            throw new Error(`Valeur par défaut invalide : ${value}. Un décimal est requis.`);
+        const [, fraction = ''] = raw.split('.');
+        if (fraction.length > field.scale || raw.replace(/[-.]/g, '').length > field.precision)
+            throw new Error(`Valeur par défaut invalide : ${value}. Elle dépasse decimal(${field.precision};${field.scale}).`);
+        return raw;
+    }
+    if (field.type === 'enum') {
+        if (!field.enumValues.includes(raw))
+            throw new Error(`Valeur par défaut invalide : ${value}.`);
+        return raw;
+    }
+    if (field.type === 'string') {
+        if (!/^[\p{L}\p{N} _.-]+$/u.test(raw))
+            throw new Error(`Valeur par défaut invalide : ${value}.`);
+        return raw;
+    }
+    throw new Error(`Les valeurs par défaut ne sont pas supportées pour le type ${field.type}.`);
+}
+function parseConstraints(raw, field, value) {
+    if (!raw)
+        return {};
+    const constraints = {};
+    for (const entry of raw.split(';')) {
+        const [key, rawValue] = entry.split('=', 2);
+        if (!key || (rawValue === undefined && key !== 'index'))
+            throw new Error(`Contrainte invalide : ${value}.`);
+        if (key === 'index') {
+            if (rawValue !== undefined || constraints.indexed)
+                throw new Error(`Contrainte invalide : ${value}.`);
+            constraints.indexed = true;
+            continue;
+        }
+        if (!rawValue || ['length', 'min', 'max', 'default'].includes(key) === false)
+            throw new Error(`Contrainte invalide : ${value}.`);
+        if (key === 'length') {
+            if (field.type !== 'string' || constraints.length !== undefined)
+                throw new Error(`La contrainte length est réservée aux chaînes : ${value}.`);
+            constraints.length = parsePositiveInteger(rawValue, 'Longueur', value);
+        }
+        else if (key === 'min' || key === 'max') {
+            if (field.type !== 'number' && field.type !== 'integer')
+                throw new Error(`La contrainte ${key} est réservée aux nombres : ${value}.`);
+            if (constraints[key] !== undefined)
+                throw new Error(`Contrainte ${key} déclarée plusieurs fois : ${value}.`);
+            constraints[key] = parseNumber(rawValue, key === 'min' ? 'Borne minimale' : 'Borne maximale', value);
+        }
+        else {
+            if (constraints.defaultValue !== undefined)
+                throw new Error(`Valeur par défaut déclarée plusieurs fois : ${value}.`);
+            constraints.defaultValue = parseDefaultValue(rawValue, field, value);
+        }
+    }
+    if (constraints.min !== undefined && constraints.max !== undefined && constraints.min > constraints.max)
+        throw new Error(`Bornes incohérentes : ${value}. min ne peut pas dépasser max.`);
+    if (constraints.length !== undefined &&
+        typeof constraints.defaultValue === 'string' &&
+        constraints.defaultValue.length > constraints.length)
+        throw new Error(`Valeur par défaut trop longue : ${value}.`);
+    return constraints;
+}
+export function parseResourceFields(values) {
+    const names = new Set();
+    const fields = values.map((value) => {
+        const match = /^([^:]+):(.+?)(?:\{([^{}]+)\})?(\?)?(!)?$/.exec(value.trim());
+        if (!match)
+            throw new Error(`Champ invalide : ${value}. Format attendu : nom:type, avec ? (nullable) ou ! (unique).`);
+        const [, rawName, rawType, rawConstraints, optional, unique] = match;
+        if (!namePattern.test(rawName))
+            throw new Error(`Nom de champ invalide : ${rawName}.`);
+        const name = `${rawName[0].toLowerCase()}${rawName.slice(1)}`;
+        if (name === 'id')
+            throw new Error('Le champ id est géré par NestGen et ne doit pas être déclaré.');
+        if (names.has(name))
+            throw new Error(`Le champ ${name} est déclaré plusieurs fois.`);
+        names.add(name);
+        const field = {
+            name,
+            ...parseType(rawType, value),
+            nullable: Boolean(optional),
+            unique: Boolean(unique),
+        };
+        const constraints = parseConstraints(rawConstraints, field, value);
+        if (field.nullable && constraints.defaultValue !== undefined)
+            throw new Error(`Un champ nullable ne peut pas définir de valeur par défaut : ${value}.`);
+        return { ...field, ...constraints };
+    });
+    if (!fields.length)
+        throw new Error('Une ressource requiert au moins un champ métier.');
+    return fields;
+}
+export function parseResourceIndexes(values, fields, uniqueValues = []) {
+    const knownFields = new Set(fields.map((field) => field.name));
+    const indexes = [
+        ...fields.filter((field) => field.indexed).map((field) => ({ fields: [field.name], unique: false })),
+        ...values.map((value) => ({ fields: value.trim().split('+'), unique: false })),
+        ...uniqueValues.map((value) => ({ fields: value.trim().split('+'), unique: true })),
+    ];
+    const seen = new Set();
+    return indexes.map((index) => {
+        if (index.fields.length === 0 ||
+            index.fields.some((field) => !namePattern.test(field) || !knownFields.has(field)))
+            throw new Error(`Index invalide : ${index.fields.join('+')}. Chaque champ doit être déclaré dans la ressource.`);
+        if (new Set(index.fields).size !== index.fields.length)
+            throw new Error(`Index invalide : ${index.fields.join('+')}. Un champ est répété.`);
+        const key = index.fields.join('+');
+        if (seen.has(key))
+            throw new Error(`Index déclaré plusieurs fois : ${key}.`);
+        seen.add(key);
+        return index.unique ? { fields: index.fields, unique: true } : { fields: index.fields };
+    });
+}
+export function parseResourceRelations(values) {
+    const seenFields = new Set();
+    return values.map((value, index) => {
+        if (!value || typeof value !== 'object' || Array.isArray(value))
+            throw new Error(`Relation invalide à l'index ${index}. Un objet est requis.`);
+        const relation = value;
+        if (relation.type !== 'belongsTo' && relation.type !== 'manyToMany')
+            throw new Error(`Relation invalide à l'index ${index}. Les types belongsTo et manyToMany sont supportés.`);
+        if (typeof relation.target !== 'string' || !resourceNamePattern.test(relation.target))
+            throw new Error(`Relation invalide à l'index ${index}. target doit être un nom de ressource valide.`);
+        if (relation.field !== undefined && (typeof relation.field !== 'string' || !namePattern.test(relation.field)))
+            throw new Error(`Relation invalide à l'index ${index}. field doit être un identifiant valide.`);
+        if (relation.inverse !== undefined &&
+            (typeof relation.inverse !== 'string' || !namePattern.test(relation.inverse)))
+            throw new Error(`Relation invalide à l'index ${index}. inverse doit être un identifiant valide.`);
+        if (relation.nullable !== undefined && typeof relation.nullable !== 'boolean')
+            throw new Error(`Relation invalide à l'index ${index}. nullable doit être un booléen.`);
+        if (relation.onDelete !== undefined && relation.onDelete !== 'RESTRICT' && relation.onDelete !== 'SET NULL')
+            throw new Error(`Relation invalide à l'index ${index}. onDelete accepte RESTRICT ou SET NULL.`);
+        if (relation.type === 'manyToMany' && (relation.nullable !== undefined || relation.onDelete !== undefined))
+            throw new Error(`Relation invalide à l'index ${index}. manyToMany ne définit ni nullable ni onDelete.`);
+        const nullable = relation.nullable ?? false;
+        const onDelete = relation.onDelete ?? 'RESTRICT';
+        if (onDelete === 'SET NULL' && !nullable)
+            throw new Error(`Relation invalide à l'index ${index}. SET NULL requiert nullable: true.`);
+        const target = relation.target.toLowerCase();
+        const field = relation.field ? `${relation.field[0].toLowerCase()}${relation.field.slice(1)}` : undefined;
+        if (field && seenFields.has(field))
+            throw new Error(`Relation invalide à l'index ${index}. Le champ ${field} est déclaré plusieurs fois.`);
+        if (field)
+            seenFields.add(field);
+        return {
+            type: relation.type,
+            target,
+            field,
+            inverse: relation.inverse ? `${relation.inverse[0].toLowerCase()}${relation.inverse.slice(1)}` : undefined,
+            nullable,
+            onDelete,
+        };
+    });
+}
+const filterOperatorsByType = {
+    string: new Set(['eq', 'neq', 'contains']),
+    number: new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte']),
+    integer: new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte']),
+    decimal: new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte']),
+    boolean: new Set(['eq', 'neq']),
+    date: new Set(['eq', 'neq', 'gt', 'gte', 'lt', 'lte']),
+    uuid: new Set(['eq', 'neq']),
+    enum: new Set(['eq', 'neq']),
+};
+export function parseResourceListOptions(value, fields) {
+    if (value === undefined)
+        return { cursor: false, filters: {}, sort: [], search: [] };
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('list doit être un objet.');
+    const list = value;
+    if (Object.keys(list).some((key) => !['cursor', 'filters', 'sort', 'search'].includes(key)))
+        throw new Error('list contient une propriété inconnue.');
+    if (list.cursor !== undefined && typeof list.cursor !== 'boolean')
+        throw new Error('list.cursor doit être un booléen.');
+    const knownFields = new Map(fields.map((field) => [field.name, field]));
+    const filtersRaw = list.filters ?? {};
+    if (!filtersRaw || typeof filtersRaw !== 'object' || Array.isArray(filtersRaw))
+        throw new Error('list.filters doit être un objet.');
+    const filters = {};
+    for (const [name, operators] of Object.entries(filtersRaw)) {
+        const field = knownFields.get(name);
+        if (!field)
+            throw new Error(`list.filters.${name} cible un champ inconnu.`);
+        if (!Array.isArray(operators) ||
+            operators.length === 0 ||
+            operators.some((operator) => typeof operator !== 'string'))
+            throw new Error(`list.filters.${name} doit contenir au moins un opérateur.`);
+        const normalized = operators;
+        if (new Set(normalized).size !== normalized.length)
+            throw new Error(`list.filters.${name} contient un opérateur répété.`);
+        if (normalized.some((operator) => !filterOperatorsByType[field.type].has(operator)))
+            throw new Error(`list.filters.${name} contient un opérateur incompatible avec ${field.type}.`);
+        filters[name] = normalized;
+    }
+    const parseFieldList = (key, allowed) => {
+        const values = list[key] ?? [];
+        if (!Array.isArray(values) || values.some((entry) => typeof entry !== 'string'))
+            throw new Error(`list.${key} doit être un tableau de noms de champs.`);
+        if (new Set(values).size !== values.length)
+            throw new Error(`list.${key} contient un champ répété.`);
+        for (const name of values) {
+            const field = knownFields.get(name);
+            if (!field || !allowed(field))
+                throw new Error(`list.${key}.${name} n'est pas autorisé.`);
+        }
+        return values;
+    };
+    return {
+        cursor: list.cursor ?? false,
+        filters,
+        sort: parseFieldList('sort', () => true),
+        search: parseFieldList('search', (field) => field.type === 'string'),
+    };
+}
+export function typescriptType(field) {
+    return field.type === 'number' || field.type === 'integer'
+        ? 'number'
+        : field.type === 'boolean'
+            ? 'boolean'
+            : field.type === 'date'
+                ? 'Date'
+                : 'string';
+}
+export function prismaType(field) {
+    const type = field.type === 'number'
+        ? 'Float'
+        : field.type === 'integer'
+            ? 'Int'
+            : field.type === 'decimal'
+                ? 'Decimal'
+                : field.type === 'boolean'
+                    ? 'Boolean'
+                    : field.type === 'date'
+                        ? 'DateTime'
+                        : 'String';
+    return `${type}${field.nullable ? '?' : ''}${field.unique ? ' @unique' : ''}`;
+}

package/examples/store-api/README.md

@@ -0,0 +1,76 @@
+# Exemple Store API — NestGen CLI 0.2.1
+
+Cette application exemple décrit une API de vente avec des clients, produits, commandes et lignes de commande. Elle est validée avec `nestgen-cli@0.2.1` et TypeORM, avec le profil d’architecture `advanced`.
+
+Les fichiers de `definitions/` sont la source de vérité. Ils restent volontairement déclaratifs : l’application est reconstruite par le CLI au lieu de conserver une copie de fichiers générés qui pourrait diverger du produit.
+
+## Parcours reproductible
+
+Créez un dossier de travail, installez la version exacte du CLI puis générez le projet Nest avec PostgreSQL et Swagger :
+
+```bash
+mkdir nestgen-store-api && cd nestgen-store-api
+npm init --yes
+npm install nestgen-cli@0.2.1
+
+./node_modules/.bin/nestgen init store-api \
+  --no-interactive \
+  --project-path ./generated \
+  --package-manager npm \
+  --orm typeorm \
+  --docker \
+  --swagger \
+  --no-operations \
+  --no-git \
+  --modules ''
+```
+
+Copiez les définitions fournies par le paquet dans le projet, puis générez-les dans l’ordre indiqué. Les relations ciblent une ressource déjà générée ; cet ordre est donc un contrat de l’exemple.
+
+```bash
+cd generated/store-api
+cp -R ../../node_modules/nestgen-cli/examples/store-api/definitions .
+
+../../node_modules/.bin/nestgen config init --orm typeorm --profile advanced --package-manager npm
+../../node_modules/.bin/nestgen resource --file definitions/customers.resource.json
+../../node_modules/.bin/nestgen resource --file definitions/products.resource.json
+../../node_modules/.bin/nestgen resource --file definitions/orders.resource.json
+../../node_modules/.bin/nestgen resource --file definitions/order-items.resource.json
+```
+
+La commande de copie doit conserver les fichiers JSON inchangés. Les chemins sont relatifs au dossier initial : adaptez-les si vous utilisez un autre emplacement de travail.
+
+## Schéma métier et migrations
+
+`customer.email` et `product.sku` sont uniques. Une commande référence obligatoirement un client. Une ligne de commande référence une commande et un produit, et la paire `orderId + productId` est unique : un même produit n’apparaît qu’une fois par commande. Les relations utilisent `RESTRICT`, afin d’empêcher la suppression d’un client, produit ou commande encore référencé.
+
+Générez et appliquez une migration explicite avant de démarrer l’API :
+
+```bash
+cp .env.example .env
+docker compose up --detach postgres
+npx typeorm-ts-node-commonjs migration:generate \
+  src/database/migrations/CreateStoreSchema \
+  --dataSource src/database/data-source.ts
+npx typeorm-ts-node-commonjs migration:run \
+  --dataSource src/database/data-source.ts
+npm run start:dev
+```
+
+Vous pouvez ensuite créer un client, un produit, une commande avec son `customerId`, puis une ligne de commande avec les identifiants de commande et de produit. Swagger est disponible sur `http://localhost:3000/api` lorsque l’option a été activée durant `init`.
+
+Pour faire évoluer le modèle, modifiez une définition, inspectez le plan et la revue de risque, puis générez la migration vous-même :
+
+```bash
+../../node_modules/.bin/nestgen resource \
+  --file definitions/customers.resource.json \
+  --update \
+  --migration-name add-customer-phone \
+  --dry-run
+```
+
+Le CLI ne crée ni n’applique la migration : relisez le diff et exécutez la commande TypeORM affichée seulement après validation.
+
+## Validation maintenue
+
+Depuis le dépôt NestGen, `npm run test:example` reconstruit dans un répertoire temporaire les quatre ressources via le binaire CLI. Le test vérifie les contraintes métier, les relations TypeORM, l’unicité de ligne de commande et le plan de migration. La CI l’exécute avec les tests d’intégration ; le paquet npm vérifie aussi que l’exemple est distribué.

package/examples/store-api/definitions/customers.resource.json

@@ -0,0 +1,14 @@
+{
+    "version": 1,
+    "name": "customer",
+    "route": "customers",
+    "table": "customers",
+    "orm": "typeorm",
+    "profile": "advanced",
+    "fields": ["email:string{length=254}!", "name:string{length=120}"],
+    "list": {
+        "filters": { "email": ["eq", "contains"] },
+        "search": ["email", "name"],
+        "sort": ["email", "name"]
+    }
+}

package/examples/store-api/definitions/order-items.resource.json

@@ -0,0 +1,26 @@
+{
+    "version": 1,
+    "name": "order-item",
+    "route": "order-items",
+    "table": "order_items",
+    "orm": "typeorm",
+    "profile": "advanced",
+    "fields": ["quantity:integer{min=1}", "unitPrice:decimal(12;2)"],
+    "relations": [
+        {
+            "type": "belongsTo",
+            "target": "order",
+            "field": "order",
+            "inverse": "items",
+            "onDelete": "RESTRICT"
+        },
+        {
+            "type": "belongsTo",
+            "target": "product",
+            "field": "product",
+            "inverse": "orderItems",
+            "onDelete": "RESTRICT"
+        }
+    ],
+    "uniqueIndexes": ["orderId+productId"]
+}

package/examples/store-api/definitions/orders.resource.json

@@ -0,0 +1,22 @@
+{
+    "version": 1,
+    "name": "order",
+    "route": "orders",
+    "table": "orders",
+    "orm": "typeorm",
+    "profile": "advanced",
+    "fields": ["reference:string{length=64}!", "status:enum(DRAFT|PLACED|CANCELLED){default=DRAFT}"],
+    "relations": [
+        {
+            "type": "belongsTo",
+            "target": "customer",
+            "field": "customer",
+            "inverse": "orders",
+            "onDelete": "RESTRICT"
+        }
+    ],
+    "list": {
+        "filters": { "status": ["eq"] },
+        "sort": ["reference", "status"]
+    }
+}

package/examples/store-api/definitions/products.resource.json

@@ -0,0 +1,19 @@
+{
+    "version": 1,
+    "name": "product",
+    "route": "products",
+    "table": "products",
+    "orm": "typeorm",
+    "profile": "advanced",
+    "fields": [
+        "sku:string{length=64}!",
+        "name:string{length=160}",
+        "unitPrice:decimal(12;2)",
+        "stock:integer{min=0;default=0}"
+    ],
+    "list": {
+        "filters": { "sku": ["eq", "contains"], "stock": ["gte", "lt"] },
+        "search": ["sku", "name"],
+        "sort": ["sku", "unitPrice", "stock"]
+    }
+}

package/examples/store-api/nestgen.example.json

@@ -0,0 +1,7 @@
+{
+    "version": 1,
+    "cliVersion": "0.2.1",
+    "orm": "typeorm",
+    "profile": "advanced",
+    "resources": ["customers", "products", "orders", "order-items"]
+}