@rvoh/dream 1.5.0 → 1.5.2

package/dist/cjs/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -94,6 +94,42 @@ class DreamMigrationHelpers {
     ALTER TABLE ${kysely_1.sql.table(table)} DROP CONSTRAINT IF EXISTS ${kysely_1.sql.table(constraintName)};
   `.execute(db);
     }
+    /**
+     * Forces a new transaction boundary in migration execution.
+     *
+     * When called in a migration file, this method ensures that any existing transaction
+     * is committed before this migration runs, and a new transaction is started before the
+     * migration in this file. This is essential for migrations that depend on previously
+     * committed changes.
+     *
+     * Some database operations require that dependent changes be committed before they can
+     * be executed. For example, check constraints that reference enum values require those
+     * enum values to be committed to the database first.
+     *
+     * ```ts
+     * // first migration file: Add enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   await DreamMigrationHelpers.addEnumValue(db, {
+     *     enumName: 'user_status',
+     *     value: 'premium'
+     *   })
+     * }
+     *
+     * // second migration file: Add check constraint that depends on the enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   DreamMigrationHelpers.newTransaction() // Ensure enum value is committed first
+     *
+     *   await db.schema
+     *     .alterTable('users')
+     *     .addCheckConstraint(
+     *       'check_premium_users',
+     *       sql`status = 'premium' OR credits < 100`
+     *     )
+     *     .execute()
+     * }
+     * ```
+     */
+    static newTransaction() { }
     /**
      * Drop a value from an enum and replace it (or optionally remove it from array columns)
      *

package/dist/cjs/src/decorators/field/sortable/helpers/setPosition.js

@@ -147,7 +147,13 @@ function applySortableScopesToQuery(dream, kyselyQuery, whereValueCB, scope) {
     for (const singleScope of (0, scopeArray_js_1.default)(scope)) {
         const column = (0, getColumnForSortableScope_js_1.default)(dream, singleScope);
         if (column) {
-            kyselyQuery = kyselyQuery.where(column, '=', whereValueCB(column));
+            const columnValue = whereValueCB(column);
+            if (columnValue === null) {
+                kyselyQuery = kyselyQuery.where(column, 'is', null);
+            }
+            else {
+                kyselyQuery = kyselyQuery.where(column, '=', columnValue);
+            }
         }
     }
     return kyselyQuery;

package/dist/cjs/src/dream/QueryDriver/Kysely.js

@@ -61,11 +61,11 @@ const executeDatabaseQuery_js_1 = require("../internal/executeDatabaseQuery.js")
 const orderByDirection_js_1 = require("../internal/orderByDirection.js");
 const shouldBypassDefaultScope_js_1 = require("../internal/shouldBypassDefaultScope.js");
 const SimilarityBuilder_js_1 = require("../internal/similarity/SimilarityBuilder.js");
+const softDeleteDream_js_1 = require("../internal/softDeleteDream.js");
 const sqlResultToDreamInstance_js_1 = require("../internal/sqlResultToDreamInstance.js");
 const Query_js_1 = require("../Query.js");
 const Base_js_1 = require("./Base.js");
 const runMigration_js_1 = require("./helpers/kysely/runMigration.js");
-const softDeleteDream_js_1 = require("../internal/softDeleteDream.js");
 class KyselyQueryDriver extends Base_js_1.default {
     // ATTENTION FRED
     // stop trying to make this async. You never learn...
@@ -1081,11 +1081,11 @@ class KyselyQueryDriver extends Base_js_1.default {
         return (0, kysely_1.sql) `FALSE`;
     }
     notInArrayWithNullExpressionBuilder(eb, a, b, c) {
-        const isNullStatement = eb(a, 'is not', null);
+        const isNotNullStatement = eb(a, 'is not', null);
         const compactedC = (0, compact_js_1.default)(c);
         if (compactedC.length)
-            return eb.and([eb(a, 'not in', compactedC), isNullStatement]);
-        return isNullStatement;
+            return eb.and([eb(a, 'not in', compactedC), isNotNullStatement]);
+        return isNotNullStatement;
     }
     dreamWhereStatementToExpressionBuilderParts(attr, val) {
         let a;

package/dist/cjs/src/dream/QueryDriver/helpers/kysely/runMigration.js

@@ -66,7 +66,8 @@ async function findNextMigrationRequiringNewTransaction(migrator, { ignore } = {
     const notYetRunMigrations = (await migrator.getMigrations()).filter(migrationInfo => !migrationInfo.executedAt && migrationInfo.name !== ignore);
     for (const notYetRunMigration of notYetRunMigrations) {
         const upAndDownString = notYetRunMigration.migration.up.toString() + (notYetRunMigration.migration.down || '').toString();
-        const migrationRequiresNewTransaction = upAndDownString.includes('DreamMigrationHelpers.dropEnumValue');
+        const migrationRequiresNewTransaction = upAndDownString.includes('DreamMigrationHelpers.dropEnumValue') ||
+            upAndDownString.includes('DreamMigrationHelpers.newTransaction');
         if (migrationRequiresNewTransaction)
             return notYetRunMigration;
     }

package/dist/cjs/src/helpers/sanitizeString.js

@@ -0,0 +1,49 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = sanitizeString;
+function sanitizeString(value, sanitizationStrategy) {
+    switch (sanitizationStrategy) {
+        case 'unicodeString':
+            return sanitizeStringUnicodeStringStrategy(value);
+        case 'htmlEntity':
+            return sanitizeStringHtmlEntityStrategy(value);
+        default:
+            if (typeof sanitizationStrategy === 'function')
+                return sanitizationStrategy(value);
+            throw new UnrecognizedAttributeSerializationSanitizationStrategy(sanitizationStrategy);
+    }
+}
+function sanitizeStringUnicodeStringStrategy(str) {
+    if (str === undefined || str === null)
+        return str;
+    return str
+        .replace(/\\/g, '\\u005c')
+        .replace(/&/g, '\\u0026')
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/\//g, '\\u002f')
+        .replace(/'/g, '\\u0027')
+        .replace(/"/g, '\\u0022');
+}
+function sanitizeStringHtmlEntityStrategy(str) {
+    if (str === undefined || str === null)
+        return str;
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\//g, '&#x2F;')
+        .replace(/'/g, '&#x27;')
+        .replace(/"/g, '&quot;');
+}
+class UnrecognizedAttributeSerializationSanitizationStrategy extends Error {
+    sanitizationStrategy;
+    constructor(sanitizationStrategy) {
+        super();
+        this.sanitizationStrategy = sanitizationStrategy;
+    }
+    get message() {
+        return `Unrecognized attribute serialization sanitization strategy:
+${this.sanitizationStrategy.toString()}`;
+    }
+}

package/dist/cjs/src/index.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.intersection = exports.hyphenize = exports.groupBy = exports.globalClassNameFromFullyQualifiedModelName = exports.Env = exports.DreamLogos = exports.DateTime = exports.compact = exports.cloneDeepSafe = exports.generateDream = exports.capitalize = exports.camelize = exports.CalendarDate = exports.Benchmark = exports.ValidationError = exports.RecordNotFound = exports.GlobalNameNotSet = exports.NotNullViolation = exports.DataTypeColumnTypeMismatch = exports.CheckConstraintViolation = exports.CreateOrFindByFailedToCreateAndFind = exports.NonLoadedAssociation = exports.Encrypt = exports.PostgresQueryDriver = exports.KyselyQueryDriver = exports.QueryDriverBase = exports.Query = exports.DreamTransaction = exports.openapiShorthandPrimitiveTypes = exports.openapiPrimitiveTypes = exports.DreamConst = exports.Dream = exports.DreamAppAllowedPackageManagersEnumValues = exports.DreamApp = exports.lookupClassByGlobalName = exports.DreamImporter = exports.Decorators = exports.STI = exports.SoftDelete = exports.ReplicaSafe = exports.validateTable = exports.validateColumn = exports.DreamMigrationHelpers = exports.untypedDb = exports.pgErrorType = exports.dreamDbConnections = exports.closeAllDbConnections = exports.DreamCLI = exports.CliFileWriter = exports.DreamBin = void 0;
-exports.ObjectSerializerBuilder = exports.DreamSerializerBuilder = exports.ObjectSerializer = exports.DreamSerializer = exports.serializerNameFromFullyQualifiedModelName = exports.isDreamSerializer = exports.inferSerializersFromDreamClassOrViewModelClass = exports.inferSerializerFromDreamOrViewModel = exports.ops = exports.uniq = exports.uncapitalize = exports.expandStiClasses = exports.standardizeFullyQualifiedModelName = exports.sortObjectByValue = exports.sortObjectByKey = exports.sortBy = exports.sort = exports.snakeify = exports.round = exports.range = exports.Range = exports.sharedPathPrefix = exports.relativeDreamPath = exports.dreamPath = exports.pascalize = exports.normalizeUnicode = exports.loadRepl = exports.isEmpty = void 0;
+exports.ObjectSerializerBuilder = exports.DreamSerializerBuilder = exports.ObjectSerializer = exports.DreamSerializer = exports.serializerNameFromFullyQualifiedModelName = exports.isDreamSerializer = exports.inferSerializersFromDreamClassOrViewModelClass = exports.inferSerializerFromDreamOrViewModel = exports.ops = exports.uniq = exports.uncapitalize = exports.expandStiClasses = exports.standardizeFullyQualifiedModelName = exports.sortObjectByValue = exports.sortObjectByKey = exports.sortBy = exports.sort = exports.snakeify = exports.sanitizeString = exports.round = exports.range = exports.Range = exports.sharedPathPrefix = exports.relativeDreamPath = exports.dreamPath = exports.pascalize = exports.normalizeUnicode = exports.loadRepl = exports.isEmpty = void 0;
 var index_js_1 = require("./bin/index.js");
 Object.defineProperty(exports, "DreamBin", { enumerable: true, get: function () { return index_js_1.default; } });
 var CliFileWriter_js_1 = require("./cli/CliFileWriter.js");
@@ -117,6 +117,8 @@ Object.defineProperty(exports, "Range", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "range", { enumerable: true, get: function () { return range_js_1.default; } });
 var round_js_1 = require("./helpers/round.js");
 Object.defineProperty(exports, "round", { enumerable: true, get: function () { return round_js_1.default; } });
+var sanitizeString_js_1 = require("./helpers/sanitizeString.js");
+Object.defineProperty(exports, "sanitizeString", { enumerable: true, get: function () { return sanitizeString_js_1.default; } });
 var snakeify_js_1 = require("./helpers/snakeify.js");
 Object.defineProperty(exports, "snakeify", { enumerable: true, get: function () { return snakeify_js_1.default; } });
 var sort_js_1 = require("./helpers/sort.js");

package/dist/cjs/src/serializer/SerializerRenderer.js

@@ -5,6 +5,7 @@ const CalendarDate_js_1 = require("../helpers/CalendarDate.js");
 const compact_js_1 = require("../helpers/compact.js");
 const DateTime_js_1 = require("../helpers/DateTime.js");
 const round_js_1 = require("../helpers/round.js");
+const sanitizeString_js_1 = require("../helpers/sanitizeString.js");
 const snakeify_js_1 = require("../helpers/snakeify.js");
 const DreamSerializerBuilder_js_1 = require("./builders/DreamSerializerBuilder.js");
 const ObjectSerializerBuilder_js_1 = require("./builders/ObjectSerializerBuilder.js");
@@ -42,7 +43,9 @@ class SerializerRenderer {
                 case 'attribute': {
                     const outputAttributeName = this.setCase(attribute.options?.as ?? attribute.name);
                     const value = data[attribute.name] ?? attribute.options?.default;
-                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(value, attribute.options, this.passthroughData, this.renderOpts);
+                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(attribute.options?.sanitize && typeof value === 'string'
+                        ? (0, sanitizeString_js_1.default)(value, attribute.options.sanitize)
+                        : value, attribute.options, this.passthroughData, this.renderOpts);
                     return accumulator;
                 }
                 /////////////////////
@@ -55,7 +58,9 @@ class SerializerRenderer {
                     const outputAttributeName = this.setCase(attribute.options?.as ?? attribute.name);
                     const target = data[attribute.targetName];
                     const value = target?.[attribute.name] ?? attribute.options?.default;
-                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(value, attribute.options, this.passthroughData, this.renderOpts);
+                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(attribute.options?.sanitize && typeof value === 'string'
+                        ? (0, sanitizeString_js_1.default)(value, attribute.options.sanitize)
+                        : value, attribute.options, this.passthroughData, this.renderOpts);
                     return accumulator;
                 }
                 //////////////////////////////

package/dist/esm/src/db/migration-helpers/DreamMigrationHelpers.js

@@ -92,6 +92,42 @@ export default class DreamMigrationHelpers {
     ALTER TABLE ${sql.table(table)} DROP CONSTRAINT IF EXISTS ${sql.table(constraintName)};
   `.execute(db);
     }
+    /**
+     * Forces a new transaction boundary in migration execution.
+     *
+     * When called in a migration file, this method ensures that any existing transaction
+     * is committed before this migration runs, and a new transaction is started before the
+     * migration in this file. This is essential for migrations that depend on previously
+     * committed changes.
+     *
+     * Some database operations require that dependent changes be committed before they can
+     * be executed. For example, check constraints that reference enum values require those
+     * enum values to be committed to the database first.
+     *
+     * ```ts
+     * // first migration file: Add enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   await DreamMigrationHelpers.addEnumValue(db, {
+     *     enumName: 'user_status',
+     *     value: 'premium'
+     *   })
+     * }
+     *
+     * // second migration file: Add check constraint that depends on the enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   DreamMigrationHelpers.newTransaction() // Ensure enum value is committed first
+     *
+     *   await db.schema
+     *     .alterTable('users')
+     *     .addCheckConstraint(
+     *       'check_premium_users',
+     *       sql`status = 'premium' OR credits < 100`
+     *     )
+     *     .execute()
+     * }
+     * ```
+     */
+    static newTransaction() { }
     /**
      * Drop a value from an enum and replace it (or optionally remove it from array columns)
      *

package/dist/esm/src/decorators/field/sortable/helpers/setPosition.js

@@ -142,7 +142,13 @@ export function applySortableScopesToQuery(dream, kyselyQuery, whereValueCB, sco
     for (const singleScope of scopeArray(scope)) {
         const column = getColumnForSortableScope(dream, singleScope);
         if (column) {
-            kyselyQuery = kyselyQuery.where(column, '=', whereValueCB(column));
+            const columnValue = whereValueCB(column);
+            if (columnValue === null) {
+                kyselyQuery = kyselyQuery.where(column, 'is', null);
+            }
+            else {
+                kyselyQuery = kyselyQuery.where(column, '=', columnValue);
+            }
         }
     }
     return kyselyQuery;

package/dist/esm/src/dream/QueryDriver/Kysely.js

@@ -59,11 +59,11 @@ import executeDatabaseQuery from '../internal/executeDatabaseQuery.js';
 import orderByDirection from '../internal/orderByDirection.js';
 import shouldBypassDefaultScope from '../internal/shouldBypassDefaultScope.js';
 import SimilarityBuilder from '../internal/similarity/SimilarityBuilder.js';
+import softDeleteDream from '../internal/softDeleteDream.js';
 import sqlResultToDreamInstance from '../internal/sqlResultToDreamInstance.js';
 import Query from '../Query.js';
 import QueryDriverBase from './Base.js';
 import runMigration from './helpers/kysely/runMigration.js';
-import softDeleteDream from '../internal/softDeleteDream.js';
 export default class KyselyQueryDriver extends QueryDriverBase {
     // ATTENTION FRED
     // stop trying to make this async. You never learn...
@@ -1079,11 +1079,11 @@ export default class KyselyQueryDriver extends QueryDriverBase {
         return sql `FALSE`;
     }
     notInArrayWithNullExpressionBuilder(eb, a, b, c) {
-        const isNullStatement = eb(a, 'is not', null);
+        const isNotNullStatement = eb(a, 'is not', null);
         const compactedC = compact(c);
         if (compactedC.length)
-            return eb.and([eb(a, 'not in', compactedC), isNullStatement]);
-        return isNullStatement;
+            return eb.and([eb(a, 'not in', compactedC), isNotNullStatement]);
+        return isNotNullStatement;
     }
     dreamWhereStatementToExpressionBuilderParts(attr, val) {
         let a;

package/dist/esm/src/dream/QueryDriver/helpers/kysely/runMigration.js

@@ -63,7 +63,8 @@ async function findNextMigrationRequiringNewTransaction(migrator, { ignore } = {
     const notYetRunMigrations = (await migrator.getMigrations()).filter(migrationInfo => !migrationInfo.executedAt && migrationInfo.name !== ignore);
     for (const notYetRunMigration of notYetRunMigrations) {
         const upAndDownString = notYetRunMigration.migration.up.toString() + (notYetRunMigration.migration.down || '').toString();
-        const migrationRequiresNewTransaction = upAndDownString.includes('DreamMigrationHelpers.dropEnumValue');
+        const migrationRequiresNewTransaction = upAndDownString.includes('DreamMigrationHelpers.dropEnumValue') ||
+            upAndDownString.includes('DreamMigrationHelpers.newTransaction');
         if (migrationRequiresNewTransaction)
             return notYetRunMigration;
     }

package/dist/esm/src/helpers/sanitizeString.js

@@ -0,0 +1,46 @@
+export default function sanitizeString(value, sanitizationStrategy) {
+    switch (sanitizationStrategy) {
+        case 'unicodeString':
+            return sanitizeStringUnicodeStringStrategy(value);
+        case 'htmlEntity':
+            return sanitizeStringHtmlEntityStrategy(value);
+        default:
+            if (typeof sanitizationStrategy === 'function')
+                return sanitizationStrategy(value);
+            throw new UnrecognizedAttributeSerializationSanitizationStrategy(sanitizationStrategy);
+    }
+}
+function sanitizeStringUnicodeStringStrategy(str) {
+    if (str === undefined || str === null)
+        return str;
+    return str
+        .replace(/\\/g, '\\u005c')
+        .replace(/&/g, '\\u0026')
+        .replace(/</g, '\\u003c')
+        .replace(/>/g, '\\u003e')
+        .replace(/\//g, '\\u002f')
+        .replace(/'/g, '\\u0027')
+        .replace(/"/g, '\\u0022');
+}
+function sanitizeStringHtmlEntityStrategy(str) {
+    if (str === undefined || str === null)
+        return str;
+    return str
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/\//g, '&#x2F;')
+        .replace(/'/g, '&#x27;')
+        .replace(/"/g, '&quot;');
+}
+class UnrecognizedAttributeSerializationSanitizationStrategy extends Error {
+    sanitizationStrategy;
+    constructor(sanitizationStrategy) {
+        super();
+        this.sanitizationStrategy = sanitizationStrategy;
+    }
+    get message() {
+        return `Unrecognized attribute serialization sanitization strategy:
+${this.sanitizationStrategy.toString()}`;
+    }
+}

package/dist/esm/src/index.js

@@ -53,6 +53,7 @@ export { default as relativeDreamPath } from './helpers/path/relativeDreamPath.j
 export { default as sharedPathPrefix } from './helpers/path/sharedPathPrefix.js';
 export { Range, default as range } from './helpers/range.js';
 export { default as round } from './helpers/round.js';
+export { default as sanitizeString } from './helpers/sanitizeString.js';
 export { default as snakeify } from './helpers/snakeify.js';
 export { default as sort } from './helpers/sort.js';
 export { default as sortBy } from './helpers/sortBy.js';

package/dist/esm/src/serializer/SerializerRenderer.js

@@ -3,6 +3,7 @@ import CalendarDate from '../helpers/CalendarDate.js';
 import compact from '../helpers/compact.js';
 import { DateTime } from '../helpers/DateTime.js';
 import round from '../helpers/round.js';
+import sanitizeString from '../helpers/sanitizeString.js';
 import snakeify from '../helpers/snakeify.js';
 import DreamSerializerBuilder from './builders/DreamSerializerBuilder.js';
 import ObjectSerializerBuilder from './builders/ObjectSerializerBuilder.js';
@@ -40,7 +41,9 @@ export default class SerializerRenderer {
                 case 'attribute': {
                     const outputAttributeName = this.setCase(attribute.options?.as ?? attribute.name);
                     const value = data[attribute.name] ?? attribute.options?.default;
-                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(value, attribute.options, this.passthroughData, this.renderOpts);
+                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(attribute.options?.sanitize && typeof value === 'string'
+                        ? sanitizeString(value, attribute.options.sanitize)
+                        : value, attribute.options, this.passthroughData, this.renderOpts);
                     return accumulator;
                 }
                 /////////////////////
@@ -53,7 +56,9 @@ export default class SerializerRenderer {
                     const outputAttributeName = this.setCase(attribute.options?.as ?? attribute.name);
                     const target = data[attribute.targetName];
                     const value = target?.[attribute.name] ?? attribute.options?.default;
-                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(value, attribute.options, this.passthroughData, this.renderOpts);
+                    accumulator[outputAttributeName] = applyRenderingOptionsToAttribute(attribute.options?.sanitize && typeof value === 'string'
+                        ? sanitizeString(value, attribute.options.sanitize)
+                        : value, attribute.options, this.passthroughData, this.renderOpts);
                     return accumulator;
                 }
                 //////////////////////////////

package/dist/types/src/db/migration-helpers/DreamMigrationHelpers.d.ts

@@ -79,6 +79,42 @@ export default class DreamMigrationHelpers {
     static dropConstraint(db: Kysely<any>, constraintName: string, { table }: {
         table: string;
     }): Promise<void>;
+    /**
+     * Forces a new transaction boundary in migration execution.
+     *
+     * When called in a migration file, this method ensures that any existing transaction
+     * is committed before this migration runs, and a new transaction is started before the
+     * migration in this file. This is essential for migrations that depend on previously
+     * committed changes.
+     *
+     * Some database operations require that dependent changes be committed before they can
+     * be executed. For example, check constraints that reference enum values require those
+     * enum values to be committed to the database first.
+     *
+     * ```ts
+     * // first migration file: Add enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   await DreamMigrationHelpers.addEnumValue(db, {
+     *     enumName: 'user_status',
+     *     value: 'premium'
+     *   })
+     * }
+     *
+     * // second migration file: Add check constraint that depends on the enum value
+     * export async function up(db: Kysely<any>): Promise<void> {
+     *   DreamMigrationHelpers.newTransaction() // Ensure enum value is committed first
+     *
+     *   await db.schema
+     *     .alterTable('users')
+     *     .addCheckConstraint(
+     *       'check_premium_users',
+     *       sql`status = 'premium' OR credits < 100`
+     *     )
+     *     .execute()
+     * }
+     * ```
+     */
+    static newTransaction(): void;
     /**
      * Drop a value from an enum and replace it (or optionally remove it from array columns)
      *

package/dist/types/src/helpers/sanitizeString.d.ts

@@ -0,0 +1,2 @@
+import { AttributeSerializationSanitizationStrategy } from '../types/serializer.js';
+export default function sanitizeString<T extends string | null | undefined>(value: T, sanitizationStrategy: AttributeSerializationSanitizationStrategy): T;

package/dist/types/src/index.d.ts

@@ -54,6 +54,7 @@ export { default as relativeDreamPath } from './helpers/path/relativeDreamPath.j
 export { default as sharedPathPrefix } from './helpers/path/sharedPathPrefix.js';
 export { Range, default as range } from './helpers/range.js';
 export { default as round, type RoundingPrecision } from './helpers/round.js';
+export { default as sanitizeString } from './helpers/sanitizeString.js';
 export { default as snakeify } from './helpers/snakeify.js';
 export { default as sort } from './helpers/sort.js';
 export { default as sortBy } from './helpers/sortBy.js';

package/dist/types/src/serializer/builders/DreamSerializerBuilder.d.ts

@@ -1,6 +1,7 @@
 import Dream from '../../Dream.js';
-import { DreamOrViewModelSerializerKey, NonJsonDreamColumnNames, ViewModel, ViewModelClass } from '../../types/dream.js';
-import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptions, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerType } from '../../types/serializer.js';
+import { DreamOrViewModelSerializerKey, DreamVirtualColumns, NonJsonDreamColumnNames, ViewModel, ViewModelClass } from '../../types/dream.js';
+import { OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from '../../types/openapi.js';
+import { AutomaticSerializerAttributeOptions, AutomaticSerializerAttributeOptionsForType, InternalAnyTypedSerializerAttribute, InternalAnyTypedSerializerCustomAttribute, InternalAnyTypedSerializerDelegatedAttribute, InternalAnyTypedSerializerRendersMany, InternalAnyTypedSerializerRendersOne, NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption, SerializerAttributeOptionsForVirtualColumn, SerializerType } from '../../types/serializer.js';
 import { SerializerRendererOpts } from '../SerializerRenderer.js';
 export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dream, MaybeNullDataType extends Dream | null, PassthroughDataType = any, DataType extends Exclude<MaybeNullDataType, null> = Exclude<MaybeNullDataType, null>> {
     protected $typeForOpenapi: DataTypeForOpenapi;
@@ -37,6 +38,7 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
      */
     attribute<AttributeName extends NonJsonDreamColumnNames<DataType> & keyof DataType & 'type', Options extends AutomaticSerializerAttributeOptionsForType>(name: AttributeName, options?: Options): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
+    attribute<AttributeName extends DreamVirtualColumns<DataType>[number], Options extends SerializerAttributeOptionsForVirtualColumn>(name: AttributeName, options?: Options): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute<MaybeAttributeName extends NonJsonDreamColumnNames<DataType> | (keyof DataType & string), AttributeName extends MaybeAttributeName extends NonJsonDreamColumnNames<DataType> ? never : Exclude<keyof DataType, keyof Dream> & string, Options extends NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption>(name: AttributeName, options: Options): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     attribute<AttributeName extends NonJsonDreamColumnNames<DataType> & keyof DataType & string, Options extends AutomaticSerializerAttributeOptions<DataType, AttributeName>>(name: AttributeName, options?: Options): DreamSerializerBuilder<DataTypeForOpenapi, MaybeNullDataType, PassthroughDataType, DataType>;
     /**
@@ -99,7 +101,8 @@ export default class DreamSerializerBuilder<DataTypeForOpenapi extends typeof Dr
      *
      * See: {@link https://your-docs-url.com/docs/serializers/attributes | Serializer Attributes Documentation}
      */
-    customAttribute<Options extends Omit<NonAutomaticSerializerAttributeOptions, 'as'> & {
+    customAttribute<Options extends {
+        openapi: OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes;
         flatten?: boolean;
     }, CallbackFn extends () => unknown>(name: string, fn: CallbackFn, options: Options): this;
     /**

package/dist/types/src/types/associations/shared.d.ts

@@ -41,7 +41,7 @@ type OnStatementForAssociationDefinition<DB, Schema, TableName extends Associati
 export type SelfOnStatement<BaseInstance extends Dream, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = Partial<Record<keyof DB[TableName], DreamColumnNames<BaseInstance>>>;
 export type WhereStatementForJoinedAssociation<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = RecursiveWhereStatementForJoinedAssociation<JoinedAssociations, DB, Schema, WhereStatement<DB, Schema, TableName>>;
 type RecursiveWhereStatementForJoinedAssociation<JoinedAssociations extends Readonly<JoinedAssociation[]>, DB, Schema, OriginalOnStatement, Depth extends number = 0, CurrentJoinedAssociation = JoinedAssociations[0], TableName = CurrentJoinedAssociation extends JoinedAssociation ? CurrentJoinedAssociation['table'] : never, AssociationName = CurrentJoinedAssociation extends JoinedAssociation ? CurrentJoinedAssociation['alias'] : never, NonNamespacedAssociationOnStatement = TableName extends never ? never : AssociationName extends never ? never : WhereStatement<DB, Schema, TableName & AssociationTableNames<DB, Schema> & keyof DB>, NextOnStatement = NonNamespacedAssociationOnStatement extends never ? OriginalOnStatement : OriginalOnStatement & {
-    [K in keyof NonNamespacedAssociationOnStatement as `${AssociationName & string}.${K & string}`]: NonNamespacedAssociationOnStatement[K & keyof NonNamespacedAssociationOnStatement];
+    [K in keyof NonNamespacedAssociationOnStatement as `${AssociationName & string}.${K & string}`]: NonNamespacedAssociationOnStatement[K & keyof NonNamespacedAssociationOnStatement] | null;
 }> = JoinedAssociations['length'] extends 0 ? OriginalOnStatement : Depth extends MAX_JOINED_TABLES_DEPTH ? OriginalOnStatement : TableName extends never ? OriginalOnStatement : RecursiveWhereStatementForJoinedAssociation<ReadonlyTail<JoinedAssociations>, DB, Schema, NextOnStatement, Inc<Depth>>;
 export type OrderStatement<DB, Schema, TableName extends AssociationTableNames<DB, Schema> & keyof DB> = TableColumnNames<DB, TableName> | Partial<Record<TableColumnNames<DB, TableName>, OrderDir>>;
 export type LimitStatement = number;

package/dist/types/src/types/associations/shared.ts

@@ -266,8 +266,10 @@ type RecursiveWhereStatementForJoinedAssociation<
   NextOnStatement = NonNamespacedAssociationOnStatement extends never
     ? OriginalOnStatement
     : OriginalOnStatement & {
-        [K in keyof NonNamespacedAssociationOnStatement as `${AssociationName & string}.${K & string}`]: NonNamespacedAssociationOnStatement[K &
-          keyof NonNamespacedAssociationOnStatement]
+        [K in keyof NonNamespacedAssociationOnStatement as `${AssociationName & string}.${K & string}`]:
+          | NonNamespacedAssociationOnStatement[K & keyof NonNamespacedAssociationOnStatement]
+          // `| null` so that we can query for models that don't have a particular association
+          | null
       },
 > = JoinedAssociations['length'] extends 0
   ? OriginalOnStatement

package/dist/types/src/types/serializer.d.ts

@@ -5,6 +5,7 @@ import ObjectSerializerBuilder from '../serializer/builders/ObjectSerializerBuil
 import { DreamAttributeDbTypes, DreamSerializable, DreamSerializableArray, ViewModelClass } from './dream.js';
 import { DecimalOpenapiTypesIncludingDbTypes, OpenapiDescription, OpenapiSchemaBodyShorthand, OpenapiShorthandPrimitiveTypes } from './openapi.js';
 export type SerializerCasing = 'camel' | 'snake';
+export type AttributeSerializationSanitizationStrategy = 'unicodeString' | 'htmlEntity' | ((val: any) => any);
 export type DreamsOrSerializersOrViewModels = DreamSerializable | DreamSerializableArray;
 export interface InternalAnyTypedSerializerAttribute {
     type: 'attribute';
@@ -48,6 +49,7 @@ export interface InternalAnyTypedSerializerRendersMany<DataType, AttributeName e
 export type AutomaticSerializerAttributeOptions<DreamInstance extends Dream, AttributeName extends keyof DreamInstance & string> = {
     as?: string;
     default?: any;
+    sanitize?: AttributeSerializationSanitizationStrategy;
     openapi?: OpenapiDescription;
     precision?: DreamAttributeDbTypes<DreamInstance>[AttributeName] extends DecimalOpenapiTypesIncludingDbTypes ? RoundingPrecision : never;
 };
@@ -58,9 +60,16 @@ export type AutomaticSerializerAttributeOptionsForType = {
         enum?: string[] | Readonly<string[]>;
     };
 };
+export type SerializerAttributeOptionsForVirtualColumn = {
+    as?: string;
+    default?: any;
+    sanitize?: AttributeSerializationSanitizationStrategy;
+    openapi?: OpenapiDescription | OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes;
+};
 export type NonAutomaticSerializerAttributeOptions = {
     as?: string;
     default?: any;
+    sanitize?: AttributeSerializationSanitizationStrategy;
     openapi: OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes;
 };
 export type NonAutomaticSerializerAttributeOptionsWithPossibleDecimalRenderOption = NonAutomaticSerializerAttributeOptions & {

package/dist/types/src/types/serializer.ts

@@ -11,6 +11,7 @@ import {
 } from './openapi.js'
 
 export type SerializerCasing = 'camel' | 'snake'
+export type AttributeSerializationSanitizationStrategy = 'unicodeString' | 'htmlEntity' | ((val: any) => any)
 export type DreamsOrSerializersOrViewModels = DreamSerializable | DreamSerializableArray
 
 export interface InternalAnyTypedSerializerAttribute<> {
@@ -68,6 +69,7 @@ export type AutomaticSerializerAttributeOptions<
 > = {
   as?: string
   default?: any
+  sanitize?: AttributeSerializationSanitizationStrategy
   openapi?: OpenapiDescription
   precision?: DreamAttributeDbTypes<DreamInstance>[AttributeName] extends DecimalOpenapiTypesIncludingDbTypes
     ? RoundingPrecision
@@ -82,9 +84,17 @@ export type AutomaticSerializerAttributeOptionsForType = {
   }
 }
 
+export type SerializerAttributeOptionsForVirtualColumn = {
+  as?: string
+  default?: any
+  sanitize?: AttributeSerializationSanitizationStrategy
+  openapi?: OpenapiDescription | OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes
+}
+
 export type NonAutomaticSerializerAttributeOptions = {
   as?: string
   default?: any
+  sanitize?: AttributeSerializationSanitizationStrategy
   openapi: OpenapiSchemaBodyShorthand | OpenapiShorthandPrimitiveTypes
 }
 

package/docs/assets/navigation.js

@@ -1 +1 @@
-window.navigationData = "data:application/octet-stream;base64,H4sIAAAAAAAAE62bUXPjthWF/4uet0l3k2zafZNla+NZ21IlxXnodDoweS0hBgEGhJxlOvnvHZCSSAIXFyCdN4/uOd8hQRIEQPjf/5sZ+Gpmn2ZXILNDwfTL7N2sZOYw+zTLBKsqqL69lL45mELM3s1euMxnn95/+Mef7y7+BRMgc6avmQEf0a+SlANkLwslK6MZl+aRK8EMVxIhBpQkXfAlF/CL5gY0guyXSY4GZmCll1zmV/WScQH5TrW/zmVuf0bocROVec0M29UlLJQ4FtL+dc+rgpns4EeFtWQCZEozo3SFEC81kqCBFYjZ/hz1zcsyYJ2XZdR9xZF75FyJuhd3twH34u426r4tSqXRO2pQjnLu1F5hbX+pRQn3fK+bp+AnECWgFxKTRblb0JwJ/gfoqyMXefBUPV2UvNNMVizDn3FXQdFuZKbr0viQU4H2vmK+V8rzWagnJh5YAQ/KbAEJdhUU7Utdgaj/dQRdX2v+ijWwJ6F4D0reKZZDPq8qlfFAH4qpaKp5OApB9MqugqKtnn6FzCTcWgEhxV6ryuw1VGSLIiKK2ch8SvNz1Nfir1iFvBwdAcXaMLlHCM3PpM/23/mDMkt1xF5OwzpFemSC5821vdFaIa3qCCjWFQgl99VObQ0zUIDsPUVcGtDPLGvGH65sCP3ww0fsNbZQsvkJQ7oiEnh6B91KblalPbEKZ/q6FOyqNDTPCijQqYOjDm0ooWC31iSZmMvajhvy7qnbgMxBV/dM1mhGkvNN0SsJ05JXEqjgVQmSlfwaqkzzctix9WJ8WQJ0mx2gYGutStCGA355AtoJ+O1BaXNg/Uc8nnMxJQTaBl5yEHnbKVMxjpSCu1cMdPCpwKUUfMEKsIZem5i6bCYlp4Lj/vs/f3z/w4c+QRWFkoPWa8+pOb3K49LyWJqdI+14AS72/HvU/7RQUkIzYrLXwOM49TjPqryzPP0cdZ96sbkQ6nfI1yx7YXu4Z5LtQVc38lh44KgjLbMb09yDYTkzDE/ydWl8YzR/OhqkZYblJNrCvj17hzKXOfJS7PEpQ3piO0MMB7T1NB6BGkuxg2a8WXv1JN6d2t/BKwgUdi6mkvb9UeSQs3fHjgHKvcpBdH0Y+nwGdEn8lX7k8Hvjbi5gh/gCNZpEOsZmjoobn7RmmhVb9gyRhw/RjePHbkNMmJRwPmf2JPAL3xeMJs61Znize6pR7PDlHH8NOwfetL16Eu+Ra3Nkor0QOHIoiVFPg+W52CvNzcF7P7n1GO8n1gx9g925W0/grSRQuH45SqvLA0hseNRVYozTUGcuBDpScMqJtKXSBTMh2KmayHo4Fk+gaeJAk8hda15ww1/Bztupc/eFYxOS6GPI7cAU7TF8xXgmMhMJwUPzDzpluJaCsP21lBhR5XRTWMFoYlpDDJSjMtrZBj4TCQpHJdx8LTVUlR1kCrF6JkMc7dQcWafnWO3EnJWE5JxGOzFnA6kpG3hDRvtT2g1HGUcdgV19QQbGmGYU164jk1ArGEm0PXyEaSWjqO5CCEJFF0BSqPHnraebyk+7XzDDlMTok93TTeWPOqOBYUJi9D3UySbSx5zOQD8hL94j9nRT+WNOaGiYkDgmbFrOZfj1GSRonpFBrnhU0uX4xrySQ6Y3J0cf5ZDprcnxmzRkemtyfxode6nH7X/V0di18MnH0pinHcmoGz/oGpdtNJd7OqiRpFLPRxWZvHq6sfzkqSLhmJw5Lm9M1uUjT4B+qcd4a1ZlDP1M01VijI39eM3lfq0h49XgO16L8gQxYveQLFiF3HhuPcrjRSnA3dCArQKHldEMyV6AP3O/JbtKjPFzmTMDzWJh94kB+4rZgiPy9LSUiHRutxUBa+FhNco6r1p7mHMhmdAsswcxTTXG+uUAulvjWyrtbL1rmbhqGhs9aEI6/ivnK9PcXt/uS+ff3g8p33mLv+Rnwkcmjv0bqReQ6I3FN/tPgwFNlUDsNrefN/P7/67WN5v5brXZYiRPRAAVvWbYQVEh2doq8dXiZQQckbAAkbogpeYF0/UXqIOH5EhiV7frdjvY81E2H869jxVD2MfviY1uGM3VELgNlIJnzH59wki9MgHZ7m4x83Z3S5nUs7kGAQYN7qoEIjvtucAA5xppL7lhYcC5SiGEknANUIYacCCgQRXMhejvp6gCQF9IgVVRsv6SUg/Vlghzbm/L6CH5qhhybREhki0SAPhaMrs9gS/aPYIYx9UQuL2dNzADzjuvYw0EFKjZodsE2i+4S62K5VHYTbZMNMOk5oVsS2hKsps6BK2O5VWN8tsSYT6cv9Bh9kuRAHD5DLrrdOwpuB/pMXSCLT20utibpnS3IyTkRwjkoRjQFTjbz/tBXZ3CVAnvC09EAm+K0qB3xalEmIViuX0JYO5zjbSrl2PZtNxV3e1hx2molIBL+3nVnv3PkmcqR6muhsCV56khxrkUKcC+2aQ8nB70EF2ZgOjhpuzO3hTckc7QCnaf/CtcU12sJ6KAw/3dPYi/sXtgrC735YSuMNlMHcCBaTsUN4e1hmf+Fc1xNBSuneuiz9C5RtmVRl/A9veIDe/N20rEelrDrwe7bYaMniQR1kxlYrhGRAENs/+/l/M/YMx9EXURkUdJj/b6dRLDf8Pt/DfSZqe4+fUT7j0VCcBru7wA7r7IjjJUJKB2w11jPmnn7xr7+P2f//k/wkz3GeY5AAA="
+window.navigationData = "data:application/octet-stream;base64,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"