@rvoh/dream 2.40.2 → 2.42.0

package/dist/cjs/src/dream/internal/findOrCreateLookupStatement.js

@@ -0,0 +1,19 @@
+import isDatabaseArrayColumn from '../../helpers/db/types/isDatabaseArrayColumn.js';
+import ops from '../../ops/index.js';
+/**
+ * Builds the `findBy` statement that findOrCreateBy, createOrFindBy,
+ * updateOrCreateBy and createOrUpdateBy use to look up an existing record.
+ * Their attributes are both the lookup and the values to persist, so an array
+ * given for an array column is the whole array to store: the lookup compares
+ * it with `ops.equal`, matching only a record whose array equals it
+ * element-for-element, in order, instead of the `IN` a plain list means in a
+ * where clause. PostgreSQL defines no equality operator for `json`, so on a
+ * `json[]` column this lookup raises at the database, as `ops.equal` does.
+ */
+export default function findOrCreateLookupStatement(dreamClass, attributes) {
+    const lookup = dreamClass['extractAttributesFromUpdateableProperties'](attributes);
+    return Object.fromEntries(Object.entries(lookup).map(([column, value]) => [
+        column,
+        Array.isArray(value) && isDatabaseArrayColumn(dreamClass, column) ? ops.equal(value) : value,
+    ]));
+}

package/dist/cjs/src/dream/internal/updateOrCreateBy.js

@@ -1,8 +1,12 @@
+import findOrCreateLookupStatement from './findOrCreateLookupStatement.js';
 import saveDream from './saveDream.js';
 export default async function updateOrCreateBy(dreamClass, txn = null, attributes, extraOpts = {}) {
+    // where().first() rather than findBy: a value the database rejects is raised, never read as no match,
+    // so it cannot lead to creating a record that already exists
     const existingRecord = await dreamClass
         .txn(txn)
-        .findBy(dreamClass['extractAttributesFromUpdateableProperties'](attributes));
+        .where(findOrCreateLookupStatement(dreamClass, attributes))
+        .first();
     const { with: attrs, skipHooks } = extraOpts;
     if (existingRecord) {
         existingRecord.assignAttributes(attrs ?? {});

package/dist/cjs/src/encrypt/algorithms/aes-gcm/decryptAESGCM.js

@@ -2,9 +2,9 @@ import * as crypto from 'crypto';
 import DecryptionError from '../../../errors/encrypt/DecryptionError.js';
 import DecryptionParseError from '../../../errors/encrypt/DecryptionParseError.js';
 export default function decryptAESGCM(algorithm, encrypted, key) {
+    const { ciphertext, tag, iv } = unpackPayloadOrFail(encrypted);
     let plaintext;
     try {
-        const { ciphertext, tag, iv } = unpackPayloadOrFail(encrypted);
         const decipher = crypto.createDecipheriv(algorithm, Buffer.from(key, 'base64'), Buffer.from(iv, 'base64'));
         decipher.setAuthTag(Buffer.from(tag, 'base64'));
         // Decrypt to a complete plaintext Buffer and decode utf8 once, mirroring the
@@ -18,6 +18,9 @@ export default function decryptAESGCM(algorithm, encrypted, key) {
         ]).toString('utf8');
     }
     catch (cause) {
+        // The cipher's error is kept as `cause`: its messages carry no input bytes, and
+        // callers read its `code` (e.g. ERR_CRYPTO_INVALID_KEYLEN to tell a misconfigured
+        // key from an undecryptable value).
         throw Object.assign(new DecryptionError(), { cause });
     }
     try {
@@ -32,17 +35,28 @@ export default function decryptAESGCM(algorithm, encrypted, key) {
         throw new DecryptionParseError();
     }
 }
+// Every way the envelope can be malformed throws DecryptionError with no `cause`. The
+// encrypted value is caller input (a cookie, a token, a column that was never
+// encrypted), and the errors that unpacking it raises quote it: JSON.parse's
+// SyntaxError embeds a snippet of the decoded text, and Buffer.from's TypeError on a
+// non-string field echoes the field's value. Checking every field is a string here
+// means the cipher operations in decryptAESGCM only ever see strings.
 function unpackPayloadOrFail(payload) {
-    const unpackedPayload = (typeof payload === 'string' ? JSON.parse(Buffer.from(payload, 'base64').toString()) : payload);
-    if (typeof unpackedPayload !== 'object') {
-        throw new Error('Failed to unpack encrypted object. Must be an object with a ciphertext and tag property');
+    let unpackedPayload;
+    try {
+        unpackedPayload =
+            typeof payload === 'string' ? JSON.parse(Buffer.from(payload, 'base64').toString()) : payload;
+    }
+    catch {
+        throw new DecryptionError();
     }
+    if (typeof unpackedPayload !== 'object' || unpackedPayload === null)
+        throw new DecryptionError();
     const { ciphertext, tag, iv } = unpackedPayload;
-    if (!ciphertext)
-        throw new Error('invalid ciphertext found');
-    if (!tag)
-        throw new Error('invalid tag found');
-    if (!iv)
-        throw new Error('missing iv');
+    if (!isNonEmptyString(ciphertext) || !isNonEmptyString(tag) || !isNonEmptyString(iv))
+        throw new DecryptionError();
     return { ciphertext, tag, iv };
 }
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}

package/dist/cjs/src/errors/CreateOrFindByFailedToCreateAndFind.js

@@ -1,15 +1,72 @@
+export const UNDETERMINED_CREATE_OR_FIND_FAILURE = {
+    kind: 'undetermined',
+    hidingDefaultScopes: [],
+    extraAttributesMayConflict: true,
+};
 export default class CreateOrFindByFailedToCreateAndFind extends Error {
     dreamClass;
-    constructor(dreamClass) {
+    failureCause;
+    /**
+     * @param dreamClass - the model `createOrFindBy` was called on
+     * @param failureCause - what could be told about why the record that
+     * blocked the insert was not found
+     */
+    constructor(dreamClass, failureCause = UNDETERMINED_CREATE_OR_FIND_FAILURE) {
         super();
         this.dreamClass = dreamClass;
+        this.failureCause = failureCause;
     }
     get message() {
-        return `
-Failed to create instance of ${this.dreamClass.sanitizedName} and no matching model exists.
+        const name = this.dreamClass.sanitizedName;
+        const failureCause = this.failureCause;
+        switch (failureCause.kind) {
+            case 'conflictingAttributes':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and no ${name} matching the find attributes was found.
 
-The likely cause is that one of the \`createWith\` fields violates
-a uniqueness constraint.
-    `;
+The violated unique index covers the \`createWith\` ${describeAttributes(failureCause.attributes)},
+so a \`createWith\` value likely conflicts with a different record. createOrFindBy
+looks the existing record up by the find attributes only; to find a record by
+${failureCause.attributes.join(', ')}, pass it as a find attribute instead.
+        `;
+            case 'hiddenByDefaultScope':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and the ${name} matching the find attributes was not found because it is
+likely hidden by ${describeDefaultScopes(failureCause.defaultScopes)}.
+
+createOrFindBy only finds records the model's default scopes return, so it
+cannot return a hidden record. Restore the hidden record, or narrow the unique
+index so that it covers only the records the default scopes return (for
+example, a partial unique index).
+        `;
+            case 'undetermined':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and no ${name} matching the find attributes was found.
+
+Possible causes:
+${describePossibleCauses(failureCause, '`createWith`')}
+        `;
+        }
     }
 }
+export function describeDefaultScopes(scopeNames) {
+    const quoted = scopeNames.map(scopeName => `"${scopeName}"`).join(', ');
+    return scopeNames.length === 1 ? `the default scope ${quoted}` : `one of the default scopes ${quoted}`;
+}
+export function describeAttributes(attributes) {
+    return `${attributes.length === 1 ? 'attribute' : 'attributes'} ${attributes.join(', ')}`;
+}
+export function describePossibleCauses(failureCause, extraAttributesOption) {
+    const causes = [];
+    if (failureCause.hidingDefaultScopes.length)
+        causes.push(`a record matching the find attributes exists but is hidden by ${describeDefaultScopes(failureCause.hidingDefaultScopes)}`);
+    if (failureCause.extraAttributesMayConflict)
+        causes.push(`a ${extraAttributesOption} value conflicts with a different record's unique column`);
+    causes.push(`a find attribute outside the violated unique index differs from the
+    conflicting record's value`, `a hook changed a find attribute before the insert, so the lookup used
+    the original value`, 'the conflicting record was deleted between the failed insert and the lookup');
+    return causes.map(cause => `  - ${cause}`).join('\n');
+}

package/dist/cjs/src/errors/CreateOrUpdateByFailedToCreateAndUpdate.js

@@ -1,15 +1,50 @@
+import { describeAttributes, describeDefaultScopes, describePossibleCauses, UNDETERMINED_CREATE_OR_FIND_FAILURE, } from './CreateOrFindByFailedToCreateAndFind.js';
 export default class CreateOrUpdateByFailedToCreateAndUpdate extends Error {
     dreamClass;
-    constructor(dreamClass) {
+    failureCause;
+    /**
+     * @param dreamClass - the model `createOrUpdateBy` was called on
+     * @param failureCause - what could be told about why the record that
+     * blocked the insert was not found
+     */
+    constructor(dreamClass, failureCause = UNDETERMINED_CREATE_OR_FIND_FAILURE) {
         super();
         this.dreamClass = dreamClass;
+        this.failureCause = failureCause;
     }
     get message() {
-        return `
-Failed to create instance of ${this.dreamClass.sanitizedName} and no matching model exists to update.
+        const name = this.dreamClass.sanitizedName;
+        const failureCause = this.failureCause;
+        switch (failureCause.kind) {
+            case 'conflictingAttributes':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and no ${name} matching the find attributes exists to update.
 
-The likely cause is that one of the \`with\` fields violates
-a uniqueness constraint.
-    `;
+The violated unique index covers the \`with\` ${describeAttributes(failureCause.attributes)},
+so a \`with\` value likely conflicts with a different record. createOrUpdateBy
+looks the record to update up by the find attributes only; to find a record by
+${failureCause.attributes.join(', ')}, pass it as a find attribute instead.
+        `;
+            case 'hiddenByDefaultScope':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and the ${name} to update was not found because it is
+likely hidden by ${describeDefaultScopes(failureCause.defaultScopes)}.
+
+createOrUpdateBy only finds records the model's default scopes return, so it
+cannot update a hidden record. Restore the hidden record, or narrow the unique
+index so that it covers only the records the default scopes return (for
+example, a partial unique index).
+        `;
+            case 'undetermined':
+                return `
+Failed to create instance of ${name}: the insert violated a uniqueness constraint,
+and no ${name} matching the find attributes exists to update.
+
+Possible causes:
+${describePossibleCauses(failureCause, '`with`')}
+        `;
+        }
     }
 }

package/dist/cjs/src/errors/GeneratedFilesAlreadyExist.js

@@ -0,0 +1,38 @@
+export default class GeneratedFilesAlreadyExist extends Error {
+    modelName;
+    existingFiles;
+    existingMigrations;
+    flags;
+    /**
+     * @param modelName - the fully qualified model name the generator was invoked with
+     * @param existingFiles - project-relative paths of the model, spec, factory and serializer files that already exist
+     * @param existingMigrations - project-relative paths of existing migrations with the name the generator would give the model's migration
+     * @param flags - the caller's flags for overwriting and for skipping existing files; when omitted, the message names Dream's `--overwrite` and `--skip-existing` and the commands that accept them
+     */
+    constructor(modelName, existingFiles, existingMigrations, flags) {
+        super();
+        this.modelName = modelName;
+        this.existingFiles = existingFiles;
+        this.existingMigrations = existingMigrations;
+        this.flags = flags;
+    }
+    get message() {
+        const { overwrite, skip } = this.flags ?? { overwrite: '--overwrite', skip: '--skip-existing' };
+        const commandsNote = this.flags ? '' : ' g:model and g:sti-child accept both.';
+        const listing = [...this.existingFiles, ...this.existingMigrations].map(file => `  ${file}`).join('\n');
+        const migrationNote = this.existingMigrations.length
+            ? `
+The existing migration is kept even with ${overwrite}, and no second one is
+written, since it may already have run. Edit it by hand if the columns changed.
+`
+            : '';
+        return `
+Refusing to generate ${this.modelName}, because these files already exist:
+${listing}
+
+Nothing was written. To replace the model, spec, factory and serializer files,
+re-run with ${overwrite}. To keep the existing files and write only the missing
+ones, re-run with ${skip}.${commandsNote}
+${migrationNote}`;
+    }
+}

package/dist/cjs/src/errors/schema-builder/ColumnNamesDoNotRoundTrip.js

@@ -0,0 +1,28 @@
+export default class ColumnNamesDoNotRoundTrip extends Error {
+    columns;
+    constructor(columns) {
+        super();
+        this.columns = columns;
+    }
+    get message() {
+        const columnLines = this.columns.map(column => `  ${column.tableName}.${column.columnName} (${column.modelName}): its attribute ${column.attributeName} maps back to ${column.mappedColumnName}`);
+        const remedyLines = this.columns.map(column => `  rename ${column.tableName}.${column.columnName} to ${column.mappedColumnName}, or add "${column.attributeName}" to the ignoredColumns getter on ${column.modelName}`);
+        return `
+The model attribute of each of these columns maps back to a column that
+does not exist:
+
+${columnLines.join('\n')}
+
+Dream names a column's attribute by camelizing the column's name, and each
+query naming the attribute targets the attribute's snake_cased name. For
+these columns, that is a column that does not exist, so a save or update
+that sets the attribute, a where clause on it, and every leftJoinPreload
+that loads the model fail.
+
+For each column, either rename it in a migration, or, if it cannot be
+renamed, ignore it:
+
+${remedyLines.join('\n')}
+`;
+    }
+}

package/dist/cjs/src/helpers/cli/ASTConnectionBuilder.js

@@ -1,9 +1,11 @@
 import * as path from 'node:path';
+import { DreamCamelCasePlugin } from '../../db/DreamDbConnection.js';
 import dbTypesFilenameForConnection from '../../db/helpers/dbTypesFilenameForConnection.js';
 import dreamSchemaTypesFilenameForConnection from '../../db/helpers/dreamSchemaTypesFilenameForConnection.js';
 import DreamApp from '../../dream-app/index.js';
 import Query from '../../dream/Query.js';
 import { ExplicitForeignKeyRequired, InvalidComputedForeignKey, } from '../../errors/associations/InvalidComputedForeignKey.js';
+import ColumnNamesDoNotRoundTrip from '../../errors/schema-builder/ColumnNamesDoNotRoundTrip.js';
 import FailedToIdentifyAssociation from '../../errors/schema-builder/FailedToIdentifyAssociation.js';
 import camelize from '../camelize.js';
 import intersection from '../intersection.js';
@@ -47,7 +49,9 @@ export default class ASTConnectionBuilder extends ASTBuilder {
      * the connection's tables, sorted by their key in the DB interface, and its
      * enums, read through the query driver once, by this builder or by the one
      * it takes its introspection from. The tables that `tableIncludePattern`
-     * leaves out, or `tableExcludePattern` names, are left out.
+     * leaves out, or `tableExcludePattern` names, are left out. Fails, before
+     * either type file is written, when a column of a model's table does not
+     * round-trip through its attribute name (see guardColumnNamesRoundTrip).
      */
     async introspectedDatabase() {
         this.introspection ||=
@@ -58,16 +62,65 @@ export default class ASTConnectionBuilder extends ASTBuilder {
                     const credentials = DreamApp.getOrFail().dbCredentialsFor(this.connectionName);
                     const includePattern = credentials?.tableIncludePattern;
                     const excludePattern = credentials?.tableExcludePattern;
-                    return {
-                        ...database,
-                        tables: database.tables
-                            .filter(table => (!includePattern || tableMatchesPattern(table, includePattern)) &&
-                            !(excludePattern && tableMatchesPattern(table, excludePattern)))
-                            .sort((a, b) => this.tableKey(a).localeCompare(this.tableKey(b))),
-                    };
+                    const tables = database.tables
+                        .filter(table => (!includePattern || tableMatchesPattern(table, includePattern)) &&
+                        !(excludePattern && tableMatchesPattern(table, excludePattern)))
+                        .sort((a, b) => this.tableKey(a).localeCompare(this.tableKey(b)));
+                    this.guardColumnNamesRoundTrip(tables);
+                    return { ...database, tables };
                 })();
         return await this.introspection;
     }
+    /**
+     * @internal
+     *
+     * fails the sync when a column of a table that one of the connection's
+     * models is backed by is not the column its attribute maps back to: Dream
+     * names the attribute by camelizing the column name, and each query naming
+     * the attribute targets the column the connection's CamelCasePlugin derives
+     * from it, so `address_line_1` (attribute `addressLine1`, which maps back to
+     * `address_line1`) could only be written, filtered on or join-loaded as a
+     * column that does not exist. A column the table's models ignore is
+     * skipped, since nothing queries it. A table no model is backed by is left
+     * to tableData, which fails the sync on it.
+     */
+    guardColumnNamesRoundTrip(tables) {
+        const columnNameMapper = new DreamCamelCasePlugin();
+        const columnsThatDoNotRoundTrip = [];
+        for (const table of tables) {
+            const tableName = this.tableKey(table);
+            const models = this.connectionModels().filter(model => model.table === tableName);
+            if (!models.length)
+                continue;
+            const ignoredColumns = this.ignoredColumnsForTable(tableName);
+            const modelName = uniq(models.map(model => model['stiBaseClassOrOwnClass'].sanitizedName)).join(', ');
+            for (const column of table.columns) {
+                const attributeName = camelize(column.name);
+                if (ignoredColumns.has(attributeName))
+                    continue;
+                const mappedColumnName = columnNameMapper.columnNameForAttribute(attributeName);
+                if (mappedColumnName === column.name)
+                    continue;
+                columnsThatDoNotRoundTrip.push({
+                    tableName,
+                    columnName: column.name,
+                    attributeName,
+                    mappedColumnName,
+                    modelName,
+                });
+            }
+        }
+        if (columnsThatDoNotRoundTrip.length)
+            throw new ColumnNamesDoNotRoundTrip(columnsThatDoNotRoundTrip);
+    }
+    /**
+     * @internal
+     *
+     * the models on the builder's connection
+     */
+    connectionModels() {
+        return Object.values(DreamApp.getOrFail().models).filter(model => model.prototype?.connectionName === this.connectionName);
+    }
     /**
      * @internal
      *
@@ -284,8 +337,7 @@ may need to update the table getter in the corresponding Dream.
      * given table (validating the declarations; see resolveIgnoredColumns)
      */
     ignoredColumnsForTable(tableName) {
-        const dreamApp = DreamApp.getOrFail();
-        const allModels = Object.values(dreamApp.models).filter(model => model.prototype?.connectionName === this.connectionName);
+        const allModels = this.connectionModels();
         const models = allModels.filter(model => model.table === tableName);
         return resolveIgnoredColumns(models, tableName, allModels);
     }

package/dist/cjs/src/helpers/cli/generateDream.js

@@ -1,9 +1,16 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import DreamCLI from '../../cli/index.js';
+import DreamApp from '../../dream-app/index.js';
+import GeneratedFilesAlreadyExist from '../../errors/GeneratedFilesAlreadyExist.js';
+import dreamFileAndDirPaths from '../path/dreamFileAndDirPaths.js';
+import dreamPath from '../path/dreamPath.js';
 import standardizeFullyQualifiedModelName from '../standardizeFullyQualifiedModelName.js';
 import generateDreamContent from './generateDreamContent.js';
-import generateFactory from './generateFactory.js';
-import generateMigration from './generateMigration.js';
-import generateSerializer from './generateSerializer.js';
-import generateUnitSpec from './generateUnitSpec.js';
+import generateFactoryContent from './generateFactoryContent.js';
+import { buildMigration } from './generateMigration.js';
+import generateSerializerContent from './generateSerializerContent.js';
+import generateUnitSpecContent from './generateUnitSpecContent.js';
 import modelClassNameFrom from './modelClassNameFrom.js';
 import writeGeneratedFile from './writeGeneratedFile.js';
 export default async function generateDream({ fullyQualifiedModelName, columnsWithTypes, options, fullyQualifiedParentName, }) {
@@ -14,7 +21,7 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
     // the soft-delete scaffold when generating an STI child regardless of the
     // caller-provided value.
     const softDelete = !isSTI && !!options.softDelete;
-    await writeGeneratedFile({
+    const modelFile = {
         dreamPathKey: 'models',
         fileName: `${fullyQualifiedModelName}.ts`,
         content: generateDreamContent({
@@ -30,21 +37,39 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             softDelete,
         }),
         logLabel: 'dream',
-    });
-    await generateUnitSpec({ fullyQualifiedModelName });
-    await generateFactory({ fullyQualifiedModelName, columnsWithTypes, modelClassName });
+    };
+    const files = [
+        modelFile,
+        {
+            dreamPathKey: 'modelSpecs',
+            fileName: `${fullyQualifiedModelName}.spec.ts`,
+            content: generateUnitSpecContent({ fullyQualifiedModelName }),
+            logLabel: 'spec',
+        },
+        {
+            dreamPathKey: 'factories',
+            fileName: `${fullyQualifiedModelName}Factory.ts`,
+            content: generateFactoryContent({ fullyQualifiedModelName, columnsWithTypes, modelClassName }),
+            logLabel: 'factory',
+        },
+    ];
     if (options.serializer)
-        await generateSerializer({
-            fullyQualifiedModelName,
-            columnsWithTypes,
-            fullyQualifiedParentName,
-            stiBaseSerializer: options.stiBaseSerializer,
-            includeAdminSerializers: options.includeAdminSerializers,
-            includeInternalSerializers: options.includeInternalSerializers ?? false,
-            modelClassName,
+        files.push({
+            dreamPathKey: 'serializers',
+            fileName: `${fullyQualifiedModelName}Serializer.ts`,
+            content: generateSerializerContent({
+                fullyQualifiedModelName,
+                columnsWithTypes,
+                fullyQualifiedParentName,
+                stiBaseSerializer: options.stiBaseSerializer,
+                includeAdminSerializers: options.includeAdminSerializers,
+                includeInternalSerializers: options.includeInternalSerializers ?? false,
+                modelClassName,
+            }),
+            logLabel: 'serializer',
         });
-    if (columnsWithTypes.length || !isSTI) {
-        await generateMigration({
+    const migration = columnsWithTypes.length || !isSTI
+        ? buildMigration({
             connectionName: options.connectionName,
             migrationName: `Create${fullyQualifiedModelName}`,
             columnsWithTypes,
@@ -53,6 +78,72 @@ export default async function generateDream({ fullyQualifiedModelName, columnsWi
             tableName: options.tableName,
             modelClassName,
             softDelete,
+        })
+        : undefined;
+    const existingFilesMode = options.existingFiles ?? 'refuse';
+    const targets = await Promise.all(files.map(async (file) => {
+        const { relFilePath, absFilePath } = dreamFileAndDirPaths(dreamPath(file.dreamPathKey), file.fileName);
+        return { file, relFilePath, exists: await fileExists(absFilePath) };
+    }));
+    const existingTargets = targets.filter(target => target.exists);
+    const existingMigrations = migration ? await migrationsWithStem(migration) : [];
+    if (existingFilesMode === 'refuse' && (existingTargets.length || existingMigrations.length))
+        throw new GeneratedFilesAlreadyExist(fullyQualifiedModelName, existingTargets.map(target => target.relFilePath), existingMigrations, options.existingFilesFlags);
+    for (const target of targets) {
+        if (target.exists && existingFilesMode === 'skip') {
+            DreamCLI.logger.log(`[dream] kept existing ${target.file.logLabel}: ${target.relFilePath}`);
+        }
+        else {
+            await writeGeneratedFile({ ...target.file, overwrite: existingFilesMode === 'overwrite' });
+        }
+    }
+    const existingModel = existingTargets.find(target => target.file === modelFile);
+    if (existingMigrations.length) {
+        for (const existingMigration of existingMigrations)
+            DreamCLI.logger.log(`[dream] kept existing migration: ${existingMigration} (no new migration written; edit it by hand if the columns changed)`);
+    }
+    else if (migration && existingFilesMode === 'skip' && existingModel) {
+        DreamCLI.logger.log(`[dream] skipped migration: ${existingModel.relFilePath} already exists, so no migration was written (its schema may come from a migration with another name); generate one with g:migration if the schema needs to change`);
+    }
+    else if (migration) {
+        await writeGeneratedFile({
+            basePath: migration.basePath,
+            fileName: migration.fileName,
+            content: migration.content,
+            logLabel: 'migration',
         });
     }
 }
+async function fileExists(absFilePath) {
+    try {
+        await fs.lstat(absFilePath);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+/**
+ * The project-relative paths of the migrations in `migration`'s folder whose
+ * file name differs from its own only in the version prefix. This reads the
+ * folder, never the database: the generator cannot tell whether such a
+ * migration has run, and a second one duplicates it either way.
+ */
+async function migrationsWithStem(migration) {
+    const suffix = `-${migration.fileStem}.ts`;
+    let fileNames;
+    try {
+        fileNames = await fs.readdir(path.join(DreamApp.getOrFail().projectRoot, migration.basePath));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+    return fileNames
+        .filter(fileName => fileName.endsWith(suffix) && /^\d+$/.test(fileName.slice(0, -suffix.length)))
+        .sort()
+        .map(fileName => path.join(migration.basePath, fileName));
+}

package/dist/cjs/src/helpers/cli/generateMigration.js

@@ -46,11 +46,16 @@ function validTableNameOrThrow(migrationName, table) {
         throw new InvalidMigrationTableName(migrationName, table);
     return table;
 }
-export default async function generateMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
+/**
+ * Builds and validates a migration without writing it, so a caller writing
+ * several files can build them all before writing any.
+ */
+export function buildMigration({ migrationName, columnsWithTypes, connectionName, fullyQualifiedModelName, fullyQualifiedParentName, tableName: explicitTableName, modelClassName, softDelete = false, }) {
     const migrationsBasePath = connectionName === 'default'
         ? path.join(dreamPath('db'), 'migrations')
         : path.join(dreamPath('db'), 'migrations', connectionName);
-    const fileName = `${migrationVersion()}-${hyphenize(migrationName).replace(/\//g, '-')}.ts`;
+    const fileStem = hyphenize(migrationName).replace(/\//g, '-');
+    const fileName = `${migrationVersion()}-${fileStem}.ts`;
     const isSTI = !!fullyQualifiedParentName;
     let content;
     if (isSTI) {
@@ -88,10 +93,9 @@ export default async function generateMigration({ migrationName, columnsWithType
             alterMarker: toTableName ? '-to-' : fromTableName ? '-from-' : undefined,
         });
     }
-    await writeGeneratedFile({
-        basePath: migrationsBasePath,
-        fileName,
-        content,
-        logLabel: 'migration',
-    });
+    return { basePath: migrationsBasePath, fileName, fileStem, content };
+}
+export default async function generateMigration(args) {
+    const { basePath, fileName, content } = buildMigration(args);
+    await writeGeneratedFile({ basePath, fileName, content, logLabel: 'migration' });
 }

package/dist/cjs/src/helpers/cli/writeGeneratedFile.js

@@ -6,20 +6,20 @@ import dreamPath from '../path/dreamPath.js';
  * Common file-writing helper used by all Dream generators.
  * Handles directory creation, file writing, logging, and error wrapping.
  */
-export default async function writeGeneratedFile({ dreamPathKey, basePath, fileName, content, logLabel, }) {
+export default async function writeGeneratedFile({ dreamPathKey, basePath, fileName, content, logLabel, overwrite = false, }) {
     const resolvedBasePath = basePath ?? dreamPath(dreamPathKey);
     const { relFilePath, absDirPath, absFilePath } = dreamFileAndDirPaths(resolvedBasePath, fileName);
     try {
         DreamCLI.logger.log(`[dream] generating ${logLabel}: ${relFilePath}`);
         await fs.mkdir(absDirPath, { recursive: true });
-        await fs.writeFile(absFilePath, content);
+        await fs.writeFile(absFilePath, content, { flag: overwrite ? 'w' : 'wx' });
     }
     catch (error) {
         throw new Error(`
       Something happened while trying to create the ${logLabel} file:
         ${relFilePath}
 
-      Does this file already exist? Here is the error that was raised:
+      Here is the error that was raised:
         ${error.message}
     `, { cause: error });
     }