@mikro-orm/core 7.3.0-dev.0 → 7.3.0-dev.1

package/entity/EntityFactory.js

@@ -190,7 +190,7 @@ export class EntityFactory {
         const initialized = options.initialized || helper(entity).__initialized;
         this.hydrate(entity, meta, diff2, initialized ? { ...options, initialized } : options);
         // we need to update the entity data only with keys that were not present before
-        const nullVal = this.#config.get('forceUndefined') ? undefined : null;
+        const nullVal = (meta.forceUndefined ?? this.#config.get('forceUndefined')) ? undefined : null;
         Utils.keys(diff2).forEach(key => {
             const prop = meta.properties[key];
             if ([ReferenceKind.MANY_TO_ONE, ReferenceKind.ONE_TO_ONE].includes(prop.kind) &&
@@ -336,7 +336,7 @@ export class EntityFactory {
                 prop.default == null &&
                 !prop.defaultRaw &&
                 entity[prop.name] === undefined) {
-                entity[prop.name] = (this.#config.get('forceUndefined') ? undefined : null);
+                entity[prop.name] = ((meta.forceUndefined ?? this.#config.get('forceUndefined')) ? undefined : null);
             }
             if (prop.kind === ReferenceKind.EMBEDDED && entity[prop.name]) {
                 const items = prop.array ? entity[prop.name] : [entity[prop.name]];

package/entity/EntityLoader.js

@@ -458,7 +458,8 @@ export class EntityLoader {
         if ([ReferenceKind.ONE_TO_ONE, ReferenceKind.MANY_TO_ONE].includes(prop.kind) &&
             items.length !== children.length &&
             Utils.isEmpty(options.where)) {
-            const nullVal = this.#em.config.get('forceUndefined') ? undefined : null;
+            const ownerMeta = this.#metadata.find(prop.entity());
+            const nullVal = (ownerMeta.forceUndefined ?? this.#em.config.get('forceUndefined')) ? undefined : null;
             const itemsMap = new Set();
             const childrenMap = new Set();
             // `e` may be an unresolved reference here, so read the targetKey value directly instead of

package/entity/defineEntity.d.ts

@@ -631,7 +631,7 @@ type PartialWhere<TProperties, TBase> = string | FilterQuery<{
     [K in AllKeys<TProperties, TBase> & string]?: unknown;
 }>;
 /** Metadata descriptor for `defineEntity()`, combining entity options with property definitions. */
-export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined, TEmbeddable extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
+export interface EntityMetadataWithProperties<TName extends string, TTableName extends string, TProperties extends Record<string, any>, TPK extends (keyof TProperties)[] | undefined = undefined, TBase = never, TRepository = never, TForceObject extends boolean = false, TDiscriminatorColumn extends string | undefined = undefined, TDiscriminatorValue extends string | number | undefined = undefined, TBaseDiscriminatorColumn extends string | undefined = undefined, TEmbeddable extends boolean = false, TForceUndefined extends boolean = false> extends Omit<Partial<EntityMetadata<InferEntityFromProperties<TProperties, TPK, TBase, TRepository>>>, 'properties' | 'extends' | 'primaryKeys' | 'hooks' | 'discriminator' | 'discriminatorColumn' | 'discriminatorValue' | 'versionProperty' | 'concurrencyCheckKeys' | 'serializedPrimaryKey' | 'indexes' | 'uniques' | 'triggers' | 'repository' | 'filters' | 'orderBy'> {
     name: TName;
     tableName?: TTableName;
     extends?: {
@@ -656,6 +656,8 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
         };
     }>;
     forceObject?: TForceObject;
+    /** Hydrate `null` as `undefined` for this entity and infer nullable properties as `T | undefined`. */
+    forceUndefined?: TForceUndefined;
     embeddable?: TEmbeddable;
     inheritance?: 'tpt';
     orderBy?: {
@@ -707,7 +709,7 @@ export interface EntityMetadataWithProperties<TName extends string, TTableName e
     }[];
 }
 /** Defines an entity schema using property builders, with full type inference from the property definitions. */
-export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined, const TEmbeddable extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn, TEmbeddable>): EntitySchemaWithMeta<TName, TTableName, InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>, TBase, TProperties, EntityCtor<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable>>, TDiscriminatorColumn>;
+export declare function defineEntity<const TName extends string, const TTableName extends string, const TProperties extends Record<string, any>, const TPK extends (keyof TProperties)[] | undefined = undefined, const TBase = never, const TRepository = never, const TForceObject extends boolean = false, const TDiscriminatorColumn extends string | undefined = undefined, const TDiscriminatorValue extends string | number | undefined = undefined, const TBaseDiscriminatorColumn extends string | undefined = undefined, const TEmbeddable extends boolean = false, const TForceUndefined extends boolean = false>(meta: EntityMetadataWithProperties<TName, TTableName, TProperties, TPK, TBase, TRepository, TForceObject, TDiscriminatorColumn, TDiscriminatorValue, TBaseDiscriminatorColumn, TEmbeddable, TForceUndefined>): EntitySchemaWithMeta<TName, TTableName, MaybeForceUndefined<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable, TForceUndefined>, EffectiveForceUndefined<TForceUndefined, TBase>>, TBase, TProperties, EntityCtor<MaybeForceUndefined<InferEntityFromProperties<TProperties, TPK, TBase, TRepository, TForceObject, TBaseDiscriminatorColumn, TDiscriminatorValue, TEmbeddable, TForceUndefined>, EffectiveForceUndefined<TForceUndefined, TBase>>>, TDiscriminatorColumn>;
 export declare namespace defineEntity {
     export { propertyBuilders as properties };
 }
@@ -744,8 +746,17 @@ type InferColumnType<T extends string> = T extends 'int' | 'int4' | 'integer' |
 type BaseEntityMethodKeys = 'toObject' | 'toPOJO' | 'serialize' | 'assign' | 'populate' | 'init' | 'toReference';
 interface BaseEntityMethods<in out Entity extends object> extends Pick<IWrappedEntity<Entity>, BaseEntityMethodKeys> {
 }
+type MaybeForceUndefined<Entity, ForceUndefined> = [ForceUndefined] extends [true] ? {
+    [K in keyof Entity]: SwapNull<Entity[K]>;
+} : Entity;
+type SwapNull<Value> = [Value] extends [ScalarReference<infer Inner>] ? [Extract<keyof Value, symbol>] extends [never] ? ScalarReference<SwapNull<Inner>> : ScalarReference<SwapNull<Inner>> & Pick<Value, Extract<keyof Value, symbol>> : null extends Value ? Exclude<Value, null> | undefined : Value;
+type EffectiveForceUndefined<Flag, Base> = [Flag] extends [true] ? true : IsNever<Base> extends true ? false : [Base] extends [{
+    [Config]?: infer C;
+}] ? [NonNullable<C>] extends [{
+    forceUndefined: true;
+}] ? true : false : false;
 /** Infers the entity type from a `defineEntity()` properties map, resolving builders, base classes, and primary keys. */
-export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
+export type InferEntityFromProperties<Properties extends Record<string, any>, PK extends (keyof Properties)[] | undefined = undefined, Base = never, Repository = never, ForceObject extends boolean = false, BaseDiscriminatorColumn extends string | undefined = undefined, DiscriminatorValue extends string | number | undefined = undefined, Embeddable extends boolean = false, ForceUndefined extends boolean = false> = (IsNever<Base> extends true ? {} : Base extends {
     toObject(...args: any[]): any;
 } ? BaseEntityMethods<{
     -readonly [K in keyof Properties]: InferBuilderValue<MaybeReturnType<Properties[K]>>;
@@ -763,6 +774,10 @@ export type InferEntityFromProperties<Properties extends Record<string, any>, PK
     [Config]?: DefineConfig<{
         forceObject: true;
     }>;
+} : {}) & (ForceUndefined extends true ? {
+    [Config]?: DefineConfig<{
+        forceUndefined: true;
+    }>;
 } : {}) & {
     [IndexHints]?: [Omit<ExtractBaseProperties<Base>, keyof Properties> & Properties];
 };

package/hydration/ObjectHydrator.js

@@ -50,6 +50,8 @@ export class ObjectHydrator extends Hydrator {
         const lines = [];
         const context = new Map();
         const props = this.getProperties(meta, type);
+        const forceUndefined = meta.forceUndefined ?? this.config.get('forceUndefined');
+        const nullVal = forceUndefined ? 'undefined' : 'null';
         context.set('isPrimaryKey', Utils.isPrimaryKey);
         context.set('isEntity', EntityHelper.isEntity);
         context.set('isScalarReference', ScalarReference.isScalarReference);
@@ -76,7 +78,6 @@ export class ObjectHydrator extends Hydrator {
                 .join('_');
             const ret = [];
             const idx = this.#tmpIndex++;
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             if (prop.getter && !prop.setter && prop.persist === false) {
                 return [];
             }
@@ -142,7 +143,6 @@ export class ObjectHydrator extends Hydrator {
         const hydrateToOne = (prop, dataKey, entityKey) => {
             const ret = [];
             const method = type === 'reference' ? 'createReference' : 'create';
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             ret.push(`  if (data${dataKey} === null) {\n    entity${entityKey} = ${nullVal};`);
             ret.push(`  } else if (typeof data${dataKey} !== 'undefined') {`);
             // For polymorphic: instanceof check; for regular: isPrimaryKey() check
@@ -341,8 +341,6 @@ export class ObjectHydrator extends Hydrator {
                     ...hydrateProperty(childProp, prop.object, [...path, childProp.embedded[1]], childDataKey).map(l => '  ' + l));
                 });
             }
-            /* v8 ignore next */
-            const nullVal = this.config.get('forceUndefined') ? 'undefined' : 'null';
             if (prop.object) {
                 ret.push(`  } else if (data${dataKey} === null) {`);
             }
@@ -365,8 +363,7 @@ export class ObjectHydrator extends Hydrator {
             ret.push(...hydrateEmbedded(prop, [...path, `[idx_${idx}]`], `${dataKey}[idx_${idx}]`).map(l => '    ' + l));
             ret.push(`    });`);
             ret.push(`  } else if (data${dataKey} === null) {`);
-            /* v8 ignore next */
-            ret.push(`    entity${entityKey} = ${this.config.get('forceUndefined') ? 'undefined' : 'null'};`);
+            ret.push(`    entity${entityKey} = ${nullVal};`);
             ret.push(`  }`);
             return ret;
         };
@@ -396,7 +393,7 @@ export class ObjectHydrator extends Hydrator {
                 // ReferenceKind.SCALAR
                 ret.push(...hydrateScalar(prop, path, dataKey));
             }
-            if (this.config.get('forceUndefined')) {
+            if (forceUndefined) {
                 ret.push(`  if (data${dataKey} === null) entity${entityKey} = undefined;`);
             }
             return ret;

package/metadata/MetadataDiscovery.js

@@ -1062,6 +1062,7 @@ export class MetadataDiscovery {
         });
         ownProps.forEach(prop => (meta.properties[prop.name] = prop));
         meta.filters = { ...base.filters, ...meta.filters };
+        meta.forceUndefined ??= base.forceUndefined;
         if (!meta.discriminatorValue) {
             Object.values(base.properties)
                 .filter(prop => !old.includes(prop.name))

package/metadata/types.d.ts

@@ -85,6 +85,8 @@ export type EntityOptions<T, E = T extends EntityClass<infer P> ? P : T> = {
     abstract?: boolean;
     /** Disables change tracking - such entities are ignored during flush. */
     readonly?: boolean;
+    /** Hydrate `null` values as `undefined` for this entity, overriding the global `forceUndefined` option. */
+    forceUndefined?: boolean;
     /** Marks entity as {@doclink virtual-entities | virtual}. This is set automatically when you use `expression` option (unless `view` is set). */
     virtual?: boolean;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mikro-orm/core",
-  "version": "7.3.0-dev.0",
+  "version": "7.3.0-dev.1",
   "description": "TypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, PostgreSQL and SQLite databases as well as usage with vanilla JavaScript.",
   "keywords": [
     "data-mapper",

package/typings.d.ts

@@ -246,6 +246,8 @@ export type CleanTypeConfig<T> = Compute<Pick<T, Extract<keyof T, keyof TypeConf
 /** Configuration options that can be set on an entity via the `[Config]` symbol. */
 export interface TypeConfig {
     forceObject?: boolean;
+    /** Type-level marker of the `forceUndefined` entity option: `defineEntity` infers nullable properties as `T | undefined` instead of `T | null | undefined`. */
+    forceUndefined?: boolean;
 }
 declare const __selectedType: unique symbol;
 declare const __loadedType: unique symbol;
@@ -1223,6 +1225,8 @@ export interface EntityMetadata<Entity = any, Class extends EntityCtor<Entity> =
     selfReferencing?: boolean;
     hasUniqueProps?: boolean;
     readonly?: boolean;
+    /** Per-entity override of the global `forceUndefined` option. */
+    forceUndefined?: boolean;
     polymorphs?: EntityMetadata[];
     root: EntityMetadata<Entity>;
     definedProperties: Dictionary;

package/unit-of-work/UnitOfWork.js

@@ -79,7 +79,7 @@ export class UnitOfWork {
      * @internal
      */
     normalizeEntityData(meta, data) {
-        const forceUndefined = this.#em.config.get('forceUndefined');
+        const forceUndefined = meta.forceUndefined ?? this.#em.config.get('forceUndefined');
         for (const key of Utils.keys(data)) {
             const prop = meta.properties[key];
             if (!prop) {

package/utils/Utils.js

@@ -153,7 +153,7 @@ export function parseJsonSafe(value) {
 /** Collection of general-purpose utility methods used throughout the ORM. */
 export class Utils {
     static PK_SEPARATOR = '~~~';
-    static #ORM_VERSION = '7.3.0-dev.0';
+    static #ORM_VERSION = '7.3.0-dev.1';
     /** Default session variable name backing an RLS filter argument (`current_setting('mikro.<filter>.<arg>')`). */
     static getRlsSettingName(filterName, argName) {
         return `mikro.${filterName}.${argName}`;