@restforgejs/platform 5.1.7 → 5.1.20

package/generators/lib/dbschema-kit/validator/schema-validator.js

@@ -1,5 +1,11 @@
 'use strict';
 
+const {
+  SOFT_DELETE_COLUMNS,
+  SOFT_DELETE_COLUMN_TYPES,
+  SOFT_DELETE_SUFFIX_LENGTH
+} = require('../soft-delete-constants');
+
 const VALID_RELATION_TYPES = new Set(['belongsTo', 'hasOne', 'hasMany']);
 const VALID_REFERENTIAL_ACTIONS = new Set(['cascade', 'restrict', 'setNull', 'noAction']);
 const COMPARISON_OPS = new Set(['gt', 'gte', 'lt', 'lte']);
@@ -7,6 +13,14 @@ const AUTO_UPDATE_VALID_TYPES = new Set(['timestamp', 'date']);
 const TABLE_NAME_RE = /^[a-z][a-z0-9_]*$/;
 const AUTO_SUFFIX = '_auto';
 
+// --- Soft-delete (Fase 1) -------------------------------------------------
+// Nama kolom (R3), kontrak tipe (R5), dan suffix length (R7) berasal dari modul shared
+// `soft-delete-constants` (sumber kebenaran tunggal, dipakai juga oleh emitter DDL Phase 02
+// dan jalur reverse introspect Phase 03). Kontrak tipe forward (R5) di validator ini dan
+// kontrak tipe reverse di introspect-mapper kini membaca satu konstanta yang sama.
+// Reusable hanya didukung untuk tipe string (varchar/text) karena value-mutation (R9).
+const REUSABLE_STRING_TYPES = new Set(['string', 'text']);
+
 function validateSchema(ir) {
   validateTableLevel(ir);
   validateSchemaName(ir);
@@ -15,6 +29,7 @@ function validateSchema(ir) {
   validateIndexAndUniqueReferences(ir);
   validateChecks(ir);
   validateAutoUpdate(ir);
+  validateSoftDelete(ir);
 }
 
 function prefix(ir, msg) {
@@ -207,4 +222,220 @@ function validateAutoUpdate(ir) {
   }
 }
 
+// --- Soft-delete invariants (R3, R5, R7, R9) ------------------------------
+//
+// Predikat tunggal ini dipanggil dari validateSchema, sehingga seluruh command
+// schema yang memuat SDF lewat defineModel (validate/migrate/diff/apply) menegakkan
+// invariant yang sama tanpa ada jalur yang bisa melewatinya (R4).
+//
+// Catatan bahasa pesan: mengikuti gaya validator existing yang seluruhnya berbahasa
+// Inggris dengan prefix `Table '<name>': ...`. Struktur multi-baris (mis. format
+// declared/required pada R7) mengikuti contoh plan master.
+function validateSoftDelete(ir) {
+  const { fields, softDelete } = ir;
+
+  const enabled = softDelete !== undefined && softDelete !== null && softDelete.enabled === true;
+  const presentColumns = SOFT_DELETE_COLUMNS.filter((col) => fields[col] !== undefined);
+
+  // R3 (arah balik): kolom soft-delete ada tetapi enabled bukan true → ERROR.
+  if (!enabled) {
+    if (presentColumns.length > 0) {
+      throw new Error(prefix(
+        ir,
+        `soft-delete columns ${presentColumns.join(', ')} are declared in 'fields', ` +
+        `but 'softDelete.enabled' is not true. ` +
+        `Either declare 'softDelete.enabled = true', or remove these columns.`
+      ));
+    }
+    // Tabel normal: tidak ada blok softDelete dan tidak ada kolom soft-delete. OK.
+    return;
+  }
+
+  // R3 (arah maju): enabled = true tetapi ada kolom yang hilang → ERROR.
+  const missing = SOFT_DELETE_COLUMNS.filter((col) => fields[col] === undefined);
+  if (missing.length > 0) {
+    throw new Error(prefix(
+      ir,
+      `softDelete.enabled = true requires all soft-delete columns in 'fields', missing: ${missing.join(', ')}. ` +
+      `Declare is_deleted (boolean), deleted_at (timestamp), deleted_by (string), or set softDelete.enabled = false.`
+    ));
+  }
+
+  // R5: validasi tipe kolom (hanya saat soft-delete aktif dan ketiga kolom ada).
+  for (const col of SOFT_DELETE_COLUMNS) {
+    const expected = SOFT_DELETE_COLUMN_TYPES[col];
+    const actual = fields[col].type;
+    if (actual !== expected) {
+      throw new Error(prefix(
+        ir,
+        `soft-delete column '${col}' must be type '${expected}', got '${actual}'.`
+      ));
+    }
+  }
+
+  // R7 + R9: validasi tiap field reusable.
+  if (softDelete.reusable !== undefined) {
+    for (const entry of softDelete.reusable) {
+      validateReusableEntry(ir, entry);
+    }
+  }
+
+  // R21: tolak generate bila ada UNIQUE yang tak punya jalur reusable (composite,
+  // atau single-column non-string). Hanya tercapai saat enabled === true.
+  validateSoftDeleteUniqueReusability(ir);
+}
+
+function validateReusableEntry(ir, entry) {
+  const { fields, uniques } = ir;
+  const fieldName = entry.field;
+
+  // Entry shape: harus mereferensi field lewat nama.
+  if (typeof fieldName !== 'string' || fieldName === '') {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable entry must have a 'field' (non-empty string), got '${fieldName}'.`
+    ));
+  }
+
+  // R9.1: field reusable harus ada di `fields`.
+  const field = fields[fieldName];
+  if (field === undefined) {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable references unknown field '${fieldName}' (not declared in 'fields').`
+    ));
+  }
+
+  // R7: base length wajib dan harus integer positif.
+  const baseLength = entry.length;
+  if (baseLength === undefined || baseLength === null) {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable field '${fieldName}' is missing required 'length' (the base business-code length).`
+    ));
+  }
+  if (typeof baseLength !== 'number' || !Number.isInteger(baseLength) || baseLength <= 0) {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable field '${fieldName}' has invalid 'length' (must be a positive integer), got '${baseLength}'.`
+    ));
+  }
+
+  // R9.3: reusable harus bertipe string (varchar/text).
+  if (!REUSABLE_STRING_TYPES.has(field.type)) {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable declares '${fieldName}' as reusable, but its column type is '${field.type}'. ` +
+      `Reusable only supports string types (varchar/text) because it uses value-mutation '{code}##{uuidv7}'. ` +
+      `Change the column type to string, or remove '${fieldName}' from reusable.`
+    ));
+  }
+
+  // R9.2: reusable harus punya UNIQUE single-column (composite ditolak).
+  const uniqueState = resolveUniqueState(fieldName, field, uniques);
+  if (uniqueState === 'none') {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable field '${fieldName}' must have a single-column UNIQUE constraint, but none was found.`
+    ));
+  }
+  if (uniqueState === 'composite') {
+    throw new Error(prefix(
+      ir,
+      `softDelete.reusable field '${fieldName}' only participates in a composite UNIQUE constraint. ` +
+      `Reusable requires a single-column UNIQUE (a composite UNIQUE is a technical integrity rule, not a reusable business code).`
+    ));
+  }
+
+  // R7: lebar fisik kolom harus muat base length + suffix.
+  // Hanya berlaku untuk `string` (punya length tetap); `text` tidak terbatas panjangnya.
+  if (field.type === 'string') {
+    const required = baseLength + SOFT_DELETE_SUFFIX_LENGTH;
+    if (field.length < required) {
+      throw new Error(prefix(
+        ir,
+        `Reusable unique column '${fieldName}' is too narrow for the soft-delete suffix:\n` +
+        `    declared : string:${field.length}\n` +
+        `    required : string:${required}   (base ${baseLength} + suffix ${SOFT_DELETE_SUFFIX_LENGTH})`
+      ));
+    }
+  }
+}
+
+// Tentukan status UNIQUE sebuah field: 'single' (single-column unique, valid untuk
+// reusable), 'composite' (hanya bagian composite unique → ditolak R9.2), atau 'none'.
+// Sumber unique: shorthand `unique` (field.unique === true) maupun ir.uniques.
+function resolveUniqueState(fieldName, field, uniques) {
+  if (field.unique === true) return 'single';
+  let hasComposite = false;
+  for (const uq of uniques) {
+    if (!Array.isArray(uq.columns) || !uq.columns.includes(fieldName)) continue;
+    if (uq.columns.length === 1) return 'single';
+    hasComposite = true;
+  }
+  return hasComposite ? 'composite' : 'none';
+}
+
+// R21: gate pra-generate untuk soft-delete dengan UNIQUE tak ter-reusable.
+//
+// Mutasi nilai '{code}##{uuidv7}' yang membebaskan UNIQUE dari bentrok saat re-create
+// baris HANYA berlaku untuk UNIQUE single-column bertipe string (R9.2 + R9.3). UNIQUE
+// jenis lain tetap PENUH/non-partial (emitter create-index.js R10/R11 sengaja tidak
+// mem-partial-kan UNIQUE: uniqueness tetap penuh), sehingga membuat ulang baris dengan
+// kunci sama setelah soft-delete akan melanggar UNIQUE tanpa jalur pembebasan. Dua bentuk
+// tanpa jalur reusable:
+//   (1) composite UNIQUE (lebih dari satu kolom);
+//   (2) single-column UNIQUE bertipe non-string (date/number/uuid/...).
+// Keduanya ditolak di generate-time. Gate murni JS pada IR → identik untuk semua dialect
+// (agnostic, deterministik); tidak menyentuh DDL/index/tipe kolom.
+//
+// Hanya dipanggil dari validateSoftDelete setelah blok enabled (jadi hanya saat
+// softDelete.enabled === true). Throw pada pelanggaran pertama dengan urutan stabil:
+// sumber A (shorthand `unique`, urut Object.keys(fields)) lalu sumber B (ir.uniques).
+function validateSoftDeleteUniqueReusability(ir) {
+  const { fields, uniques } = ir;
+
+  // Sumber A: UNIQUE single-column via shorthand `unique` (field.unique === true).
+  for (const fieldName of Object.keys(fields)) {
+    const field = fields[fieldName];
+    if (field.unique !== true) continue;
+    if (!REUSABLE_STRING_TYPES.has(field.type)) {
+      throw new Error(softDeleteNonStringUniqueMessage(ir, fieldName, field.type));
+    }
+  }
+
+  // Sumber B: UNIQUE dari ir.uniques (composite maupun single-column).
+  for (const uq of uniques) {
+    const columns = Array.isArray(uq.columns) ? uq.columns : [];
+    if (columns.length > 1) {
+      throw new Error(prefix(
+        ir,
+        `softDelete.enabled = true, but the table has a composite UNIQUE (${columns.join(', ')}) ` +
+        `that cannot be freed by reusable value-mutation on soft-delete. ` +
+        `Re-creating a row with the same key after soft-delete would violate this UNIQUE. ` +
+        `Use hard-delete for process-driven tables (balances/ledgers/snapshots/period-close), ` +
+        `or make the only UNIQUE a single-column string business code.`
+      ));
+    }
+    if (columns.length === 1) {
+      const col = columns[0];
+      const field = fields[col];
+      // Eksistensi kolom sudah dijamin validateIndexAndUniqueReferences; cek defensif.
+      if (field !== undefined && !REUSABLE_STRING_TYPES.has(field.type)) {
+        throw new Error(softDeleteNonStringUniqueMessage(ir, col, field.type));
+      }
+    }
+  }
+}
+
+function softDeleteNonStringUniqueMessage(ir, column, type) {
+  return prefix(
+    ir,
+    `softDelete.enabled = true, but single-column UNIQUE '${column}' is type '${type}', ` +
+    `which cannot be freed by reusable value-mutation on soft-delete (reusable requires string/text). ` +
+    `Re-creating a row with the same value after soft-delete would violate this UNIQUE. ` +
+    `Use hard-delete, or change the unique key to a single-column string business code.`
+  );
+}
+
 module.exports = { validateSchema };

package/generators/lib/generators/dashboard-generator.js

@@ -60,7 +60,7 @@ class DashboardGenerator {
 
   /**
    * Tulis file module dashboard ke src/modules/{project}/dash-{name}.js.
-   * SQL di-embed langsung sebagai template literal — tidak ada SQL file copy.
+   * SQL di-embed langsung sebagai template literal — tidak ada SQL file copy.
    *
    * @param {string} projectName
    * @param {string} dashboardName
@@ -141,8 +141,8 @@ class DashboardGenerator {
   /**
    * Baca file SQL dari disk (saat generation time), trim trailing whitespace,
    * lalu escape karakter yang berbahaya di template literal JS:
-   *   - backtick (`) → \`
-   *   - dollar-brace (${) → \${
+   *   - backtick (`) → \`
+   *   - dollar-brace (${) → \${
    *
    * Comment SQL dibiarkan apa adanya (defensive: bisa berisi info dialect /
    * output columns yang berguna saat audit).
@@ -380,8 +380,8 @@ module.exports = router;
   /**
    * Render block cache set yang disisip setelah loop normalisasi (lowercaseKeysDeep
    * + stringifyNumericDeep) dan sebelum `res.json(response)`. TTL literal:
-   *   - bila cacheConfig.ttl numeric → emit angka literal
-   *   - bila cacheConfig.ttl null → emit `null` agar `cacheManager.set`
+   *   - bila cacheConfig.ttl numeric → emit angka literal
+   *   - bila cacheConfig.ttl null → emit `null` agar `cacheManager.set`
    *     fallback ke env CACHE_TTL.
    */
   static _renderCacheSetBlock(cacheConfig) {

package/generators/lib/generators/processor-validation-generator.js

@@ -34,10 +34,10 @@ const FORMAT_REGEX = {
 };
 
 const FORMAT_MESSAGES = {
-  'email': 'harus berupa alamat email yang valid',
-  'url': 'harus berupa URL yang valid',
-  'phone-id': 'harus berupa nomor telepon Indonesia yang valid',
-  'uuid': 'harus berupa UUID yang valid'
+  'email': 'must be a valid email address',
+  'url': 'must be a valid URL',
+  'phone-id': 'must be a valid Indonesian phone number',
+  'uuid': 'must be a valid UUID'
 };
 
 /**
@@ -89,7 +89,7 @@ function buildFieldCheckBlock(inputField, messagePrefix, required, followUpCheck
   if (required) {
     checks.push({
       condition: `input['${safeField}'] === undefined || input['${safeField}'] === null || input['${safeField}'] === ''`,
-      message: `${messagePrefix} wajib diisi`
+      message: `${messagePrefix} is required`
     });
   }
   for (const check of followUpChecks) {
@@ -128,47 +128,47 @@ function buildFollowUpChecks(inputField, messagePrefix, fieldDef) {
       case 'string':
         checks.push({
           condition: `typeof input['${safeField}'] !== 'string'`,
-          message: `${messagePrefix} harus berupa string`
+          message: `${messagePrefix} must be a string`
         });
         break;
       case 'number':
         checks.push({
           condition: `typeof input['${safeField}'] !== 'number' && isNaN(Number(input['${safeField}']))`,
-          message: `${messagePrefix} harus berupa angka`
+          message: `${messagePrefix} must be a number`
         });
         break;
       case 'integer':
         checks.push({
           condition: `!Number.isInteger(Number(input['${safeField}']))`,
-          message: `${messagePrefix} harus berupa bilangan bulat`
+          message: `${messagePrefix} must be an integer`
         });
         break;
       case 'boolean':
         checks.push({
           condition: `typeof input['${safeField}'] !== 'boolean' && input['${safeField}'] !== 'true' && input['${safeField}'] !== 'false'`,
-          message: `${messagePrefix} harus berupa boolean`
+          message: `${messagePrefix} must be a boolean`
         });
         break;
       case 'uuid':
         checks.push({
           condition: `typeof input['${safeField}'] !== 'string'`,
-          message: `${messagePrefix} harus berupa string`
+          message: `${messagePrefix} must be a string`
         });
         checks.push({
           condition: `!${FORMAT_REGEX.uuid}.test(input['${safeField}'])`,
-          message: `${messagePrefix} harus berupa UUID yang valid`
+          message: `${messagePrefix} must be a valid UUID`
         });
         break;
       case 'array':
         checks.push({
           condition: `!Array.isArray(input['${safeField}'])`,
-          message: `${messagePrefix} harus berupa array`
+          message: `${messagePrefix} must be an array`
         });
         break;
       case 'object':
         checks.push({
           condition: `typeof input['${safeField}'] !== 'object' || Array.isArray(input['${safeField}'])`,
-          message: `${messagePrefix} harus berupa object`
+          message: `${messagePrefix} must be an object`
         });
         break;
       default:
@@ -193,7 +193,7 @@ function buildFollowUpChecks(inputField, messagePrefix, fieldDef) {
       const listLiteral = `[${safeValues.join(', ')}]`;
       checks.push({
         condition: `!${listLiteral}.includes(input['${safeField}'])`,
-        message: `${messagePrefix} tidak termasuk nilai yang diizinkan`
+        message: `${messagePrefix} is not one of the allowed values`
       });
     }
   }
@@ -202,13 +202,13 @@ function buildFollowUpChecks(inputField, messagePrefix, fieldDef) {
   if (fieldDef && Number.isInteger(fieldDef.minLength) && fieldDef.minLength >= 0) {
     checks.push({
       condition: `typeof input['${safeField}'] === 'string' && input['${safeField}'].length < ${fieldDef.minLength}`,
-      message: `${messagePrefix} minimal ${fieldDef.minLength} karakter`
+      message: `${messagePrefix} must be at least ${fieldDef.minLength} characters`
     });
   }
   if (fieldDef && Number.isInteger(fieldDef.maxLength) && fieldDef.maxLength >= 0) {
     checks.push({
       condition: `typeof input['${safeField}'] === 'string' && input['${safeField}'].length > ${fieldDef.maxLength}`,
-      message: `${messagePrefix} maksimal ${fieldDef.maxLength} karakter`
+      message: `${messagePrefix} must be at most ${fieldDef.maxLength} characters`
     });
   }