@rtpaulino/entity 0.24.2 → 0.25.0

package/dist/lib/types.d.ts

@@ -19,6 +19,14 @@ export declare const ENTITY_OPTIONS_METADATA_KEY: unique symbol;
  * Metadata key used to store entity validator methods
  */
 export declare const ENTITY_VALIDATOR_METADATA_KEY: unique symbol;
+/**
+ * Metadata key used to store polymorphic discriminator property information
+ */
+export declare const POLYMORPHIC_PROPERTY_METADATA_KEY: unique symbol;
+/**
+ * Metadata key used to store polymorphic variant information
+ */
+export declare const POLYMORPHIC_VARIANT_METADATA_KEY: unique symbol;
 /**
  * Metadata key used to store injected property information
  */
@@ -203,6 +211,23 @@ export interface PropertyOptions<T = any, C extends CtorLike<T> = AnyCtor<T> | B
      * item!: BaseItem;
      */
     discriminatorProperty?: string;
+    /**
+     * Indicates this property is a polymorphic discriminator.
+     * The property value determines which subclass variant to instantiate during parsing.
+     * Used for class hierarchies where the discriminator is part of the class definition.
+     * @example
+     * @PolymorphicProperty(SchemaPropertyType)
+     * type!: SchemaPropertyType;
+     */
+    polymorphicDiscriminator?: boolean;
+    /**
+     * The enum or union type for the polymorphic discriminator.
+     * Used for validation and schema generation (e.g., Zod enums).
+     * @example
+     * @PolymorphicProperty(SchemaPropertyType)
+     * type!: SchemaPropertyType;
+     */
+    polymorphicEnumType?: any;
 }
 /**
  * A validator function for a property.

package/dist/lib/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"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"}

package/dist/lib/types.js

@@ -13,6 +13,12 @@
 /**
  * Metadata key used to store entity validator methods
  */ export const ENTITY_VALIDATOR_METADATA_KEY = Symbol('entity:validator:metadata');
+/**
+ * Metadata key used to store polymorphic discriminator property information
+ */ export const POLYMORPHIC_PROPERTY_METADATA_KEY = Symbol('polymorphic:property:metadata');
+/**
+ * Metadata key used to store polymorphic variant information
+ */ export const POLYMORPHIC_VARIANT_METADATA_KEY = Symbol('polymorphic:variant:metadata');
 /**
  * Metadata key used to store injected property information
  */ export const INJECTED_PROPERTY_METADATA_KEY = Symbol('injected-property:metadata');

package/dist/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/types.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unsafe-function-type */\n/* eslint-disable @typescript-eslint/no-explicit-any */\n/* eslint-disable @typescript-eslint/no-wrapper-object-types */\nimport type { Problem } from './problem.js';\n\n/**\n * Metadata key used to store property information\n */\nexport const PROPERTY_METADATA_KEY = Symbol('property:metadata');\n\n/**\n * Metadata key used to store property options\n */\nexport const PROPERTY_OPTIONS_METADATA_KEY = Symbol(\n  'property:options:metadata',\n);\n\n/**\n * Metadata key used to store entity information\n */\nexport const ENTITY_METADATA_KEY = Symbol('entity:metadata');\n\n/**\n * Metadata key used to store entity options\n */\nexport const ENTITY_OPTIONS_METADATA_KEY = Symbol('entity:options:metadata');\n\n/**\n * Metadata key used to store entity validator methods\n */\nexport const ENTITY_VALIDATOR_METADATA_KEY = Symbol(\n  'entity:validator:metadata',\n);\n\n/**\n * Metadata key used to store injected property information\n */\nexport const INJECTED_PROPERTY_METADATA_KEY = Symbol(\n  'injected-property:metadata',\n);\n\n/**\n * Metadata key used to store injected property options (tokens)\n */\nexport const INJECTED_PROPERTY_OPTIONS_METADATA_KEY = Symbol(\n  'injected-property:options:metadata',\n);\n\nexport type AnyCtor<T = any> = Function & { prototype: T };\n\nexport type BuiltinCtors =\n  | StringConstructor\n  | NumberConstructor\n  | BooleanConstructor\n  | BigIntConstructor\n  | SymbolConstructor\n  | DateConstructor;\n\n/**\n * Type constructors for primitive types that can be deserialized\n * (excludes Symbol which cannot be deserialized from JSON)\n */\nexport type PrimitiveConstructor =\n  | StringConstructor\n  | NumberConstructor\n  | BooleanConstructor\n  | BigIntConstructor\n  | DateConstructor;\n\nexport type CtorLike<T> = AnyCtor<T> | BuiltinCtors;\n\nexport type InstanceOfCtorLike<C> = C extends StringConstructor\n  ? string\n  : C extends NumberConstructor\n    ? number\n    : C extends BooleanConstructor\n      ? boolean\n      : C extends BigIntConstructor\n        ? bigint\n        : C extends SymbolConstructor\n          ? symbol\n          : C extends DateConstructor\n            ? Date\n            : C extends AnyCtor<infer T>\n              ? T\n              : never;\n\n/**\n * Options for the Property decorator\n */\nexport interface PropertyOptions<\n  T = any,\n  C extends CtorLike<T> = AnyCtor<T> | BuiltinCtors,\n> {\n  /**\n   * Custom equality comparison function for this property\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns true if values are equal, false otherwise\n   */\n  equals?: (a: InstanceOfCtorLike<C>, b: InstanceOfCtorLike<C>) => boolean;\n\n  /**\n   * Type constructor for this property. Required for EntityUtils.parse() support.\n   * Use a function that returns the type constructor to support forward references.\n   * Not required for discriminated entity properties nor passthrough properties.\n   * @example\n   * @Property({ type: () => String })\n   * name!: string;\n   *\n   * @Property({ type: () => Address })\n   * address!: Address;\n   */\n  type?: () => C;\n\n  /**\n   * Whether this property is an array. Defaults to false.\n   * When true, the deserializer will map over array elements.\n   * @example\n   * @Property({ type: () => String, array: true })\n   * tags!: string[];\n   */\n  array?: boolean;\n\n  /**\n   * Whether this property is optional. Defaults to false.\n   * When true, the property can be undefined or null.\n   * When false, the property must be present and not null/undefined.\n   * @example\n   * @Property({ type: () => String, optional: true })\n   * nickname?: string;\n   */\n  optional?: boolean;\n\n  /**\n   * Whether the array can contain null/undefined elements. Defaults to false.\n   * Only applicable when array is true.\n   * When false (default), null/undefined elements will cause an error.\n   * When true, null/undefined elements are allowed in the array.\n   * @example\n   * @Property({ type: () => String, array: true, sparse: true })\n   * tags!: (string | null)[];\n   */\n  sparse?: boolean;\n\n  /**\n   * Whether to bypass type validation and pass values through as-is.\n   * Use this for generic types like Record<string, unknown> or any.\n   * When true, no type checking or transformation is performed.\n   * Also bypasses any custom serialize/deserialize callbacks.\n   * @example\n   * @Property({ passthrough: true })\n   * metadata!: Record<string, unknown>;\n   */\n  passthrough?: boolean;\n\n  /**\n   * Whether to prevent this property from being updated via EntityUtils.update().\n   * When true, this property cannot be modified through update operations.\n   * Defaults to false, allowing the property to be updated.\n   * @example\n   * @Property({ type: () => String, preventUpdates: true })\n   * id!: string; // This property cannot be updated\n   */\n  preventUpdates?: boolean;\n\n  /**\n   * Default value for the property when not provided during deserialization.\n   * Can be a static value or a function that returns the default value.\n   * The function can be async and return a Promise.\n   * @example\n   * @Property({ type: () => String, default: 'N/A' })\n   * nickname?: string;\n   *\n   * @Property({ type: () => Date, default: () => new Date() })\n   * createdAt!: Date;\n   *\n   * @Property({ type: () => String, default: async () => await fetchDefaultValue() })\n   * value!: string;\n   */\n  default?:\n    | InstanceOfCtorLike<C>\n    | (() => InstanceOfCtorLike<C> | Promise<InstanceOfCtorLike<C>>);\n\n  /**\n   * Custom serialization function to convert the property value to JSON-compatible format.\n   * Must be paired with deserialize - both must be defined together or both omitted.\n   * Not used when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => MyClass,\n   *   serialize: (value) => ({ data: value.toData() }),\n   *   deserialize: (json) => MyClass.fromData(json.data)\n   * })\n   * myProperty!: MyClass;\n   */\n  serialize?: (value: InstanceOfCtorLike<C>) => unknown;\n\n  /**\n   * Custom deserialization function to convert JSON data back to the property type.\n   * Must be paired with serialize - both must be defined together or both omitted.\n   * Not used when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => MyClass,\n   *   serialize: (value) => ({ data: value.toData() }),\n   *   deserialize: (json) => MyClass.fromData(json.data)\n   * })\n   * myProperty!: MyClass;\n   */\n  deserialize?: (serialized: unknown) => InstanceOfCtorLike<C>;\n\n  /**\n   * Array of validator functions for this property.\n   * Each validator receives the property value and validation context.\n   * Empty array means validation passed.\n   * If the property is an array (array: true), these validators will run against each item.\n   * Use arrayValidators instead to validate the array as a whole.\n   * If passthrough is true, validators will run against the raw value.\n   * @example\n   * @Property({\n   *   type: () => String,\n   *   validators: [\n   *     (value, { createProblem }) =>\n   *       value.length > 10 ? [createProblem('Too long')] : []\n   *   ]\n   * })\n   * name!: string;\n   */\n  validators?: PropertyValidator<InstanceOfCtorLike<C>>[];\n\n  /**\n   * Array of validator functions for this property when it is an array.\n   * Each validator receives the array value and validation context.\n   * Empty array means validation passed.\n   * Only applicable when array is true.\n   * Not applicable when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => Number,\n   *   array: true,\n   *   arrayValidators: [\n   *     (value, { createProblem }) =>\n   *       value.length === 0 ? [createProblem('Array cannot be empty')] : []\n   *   ]\n   * })\n   * scores!: number[];\n   */\n  arrayValidators?: PropertyValidator<InstanceOfCtorLike<C>[]>[];\n\n  /**\n   * Indicates this property uses discriminated entity types.\n   * The discriminator property name (e.g., '__type') is used to determine the entity type at runtime.\n   * When true, serialization will include the discriminator inline with the entity.\n   * During deserialization, the discriminator value is used to lookup the entity class in EntityRegistry.\n   * @example\n   * @DiscriminatedEntityProperty({ discriminatorProperty: '__type' })\n   * item!: BaseItem; // Could be ItemA or ItemB at runtime\n   */\n  discriminated?: boolean;\n\n  /**\n   * The property name to use as the discriminator for discriminated entity properties.\n   * Defaults to '__type' if not specified.\n   * Only applicable when discriminated is true.\n   * @example\n   * @DiscriminatedEntityProperty({ discriminatorProperty: 'entityType' })\n   * item!: BaseItem;\n   */\n  discriminatorProperty?: string;\n}\n\n/**\n * A validator function for a property.\n * The validator receives the value and returns Problems with property paths relative to the value.\n * Can be synchronous or asynchronous.\n * The calling code will prepend the actual property key to all returned problems.\n *\n * @param data - Object containing the value to validate\n * @param data.value - The value to validate\n * @returns Array of Problems (empty if valid) or Promise resolving to Problems.\n *          Problems should have empty property for the value itself,\n *          or relative paths for nested properties (e.g., 'name', '[0]', 'address.street')\n *\n * @example\n * ```typescript\n * // Synchronous validator\n * (({ value }) =>\n *   value.length < 3 ? [new Problem({ property: '', message: 'Too short' })] : [])\n *\n * // Asynchronous validator\n * async ({ value }) => {\n *   const exists = await checkDatabase(value);\n *   return exists ? [] : [new Problem({ property: '', message: 'Not found' })];\n * }\n * ```\n */\nexport type PropertyValidator<T> = (data: {\n  value: T;\n}) => Problem[] | Promise<Problem[]>;\n\n/**\n * A validator function for an entity.\n * Can be synchronous or asynchronous.\n * @param instance - The entity instance to validate\n * @returns Array of Problems (empty if valid) or Promise resolving to Problems\n */\nexport type EntityValidatorFn<T = any> = (\n  instance: T,\n) => Problem[] | Promise<Problem[]>;\n\nexport interface Type<T = any> extends Function {\n  new (...args: any[]): T;\n}\n\nexport type EntityDIToken<T = any> =\n  | string\n  | symbol\n  | Function\n  | AnyCtor<T>\n  | Type<T>;\n\nexport type EntityDIProvider<T = any> =\n  | {\n      provide: EntityDIToken<T>;\n      useValue?: T;\n      useFactory?: never;\n    }\n  | {\n      provide: EntityDIToken<T>;\n      useValue?: never;\n      useFactory?: () => T | Promise<T>;\n    };\n\nexport type EntityDIFallbackFn = (token: EntityDIToken) => Promise<any>;\n\n/**\n * Generic type for safe operation results that can succeed or fail\n * @template T - The data type on success\n */\nexport type SafeOperationResult<T> = Promise<\n  | { success: true; data: T; problems: Problem[] }\n  | { success: false; data: undefined; problems: Problem[] }\n>;\n\nexport type ParseOptions = { strict?: boolean };\n"],"names":["PROPERTY_METADATA_KEY","Symbol","PROPERTY_OPTIONS_METADATA_KEY","ENTITY_METADATA_KEY","ENTITY_OPTIONS_METADATA_KEY","ENTITY_VALIDATOR_METADATA_KEY","INJECTED_PROPERTY_METADATA_KEY","INJECTED_PROPERTY_OPTIONS_METADATA_KEY"],"mappings":"AAAA,6DAA6D,GAC7D,qDAAqD,GACrD,6DAA6D,GAG7D;;CAEC,GACD,OAAO,MAAMA,wBAAwBC,OAAO,qBAAqB;AAEjE;;CAEC,GACD,OAAO,MAAMC,gCAAgCD,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAME,sBAAsBF,OAAO,mBAAmB;AAE7D;;CAEC,GACD,OAAO,MAAMG,8BAA8BH,OAAO,2BAA2B;AAE7E;;CAEC,GACD,OAAO,MAAMI,gCAAgCJ,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAMK,iCAAiCL,OAC5C,8BACA;AAEF;;CAEC,GACD,OAAO,MAAMM,yCAAyCN,OACpD,sCACA"}
+{"version":3,"sources":["../../src/lib/types.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-unsafe-function-type */\n/* eslint-disable @typescript-eslint/no-explicit-any */\n/* eslint-disable @typescript-eslint/no-wrapper-object-types */\nimport type { Problem } from './problem.js';\n\n/**\n * Metadata key used to store property information\n */\nexport const PROPERTY_METADATA_KEY = Symbol('property:metadata');\n\n/**\n * Metadata key used to store property options\n */\nexport const PROPERTY_OPTIONS_METADATA_KEY = Symbol(\n  'property:options:metadata',\n);\n\n/**\n * Metadata key used to store entity information\n */\nexport const ENTITY_METADATA_KEY = Symbol('entity:metadata');\n\n/**\n * Metadata key used to store entity options\n */\nexport const ENTITY_OPTIONS_METADATA_KEY = Symbol('entity:options:metadata');\n\n/**\n * Metadata key used to store entity validator methods\n */\nexport const ENTITY_VALIDATOR_METADATA_KEY = Symbol(\n  'entity:validator:metadata',\n);\n\n/**\n * Metadata key used to store polymorphic discriminator property information\n */\nexport const POLYMORPHIC_PROPERTY_METADATA_KEY = Symbol(\n  'polymorphic:property:metadata',\n);\n\n/**\n * Metadata key used to store polymorphic variant information\n */\nexport const POLYMORPHIC_VARIANT_METADATA_KEY = Symbol(\n  'polymorphic:variant:metadata',\n);\n\n/**\n * Metadata key used to store injected property information\n */\nexport const INJECTED_PROPERTY_METADATA_KEY = Symbol(\n  'injected-property:metadata',\n);\n\n/**\n * Metadata key used to store injected property options (tokens)\n */\nexport const INJECTED_PROPERTY_OPTIONS_METADATA_KEY = Symbol(\n  'injected-property:options:metadata',\n);\n\nexport type AnyCtor<T = any> = Function & { prototype: T };\n\nexport type BuiltinCtors =\n  | StringConstructor\n  | NumberConstructor\n  | BooleanConstructor\n  | BigIntConstructor\n  | SymbolConstructor\n  | DateConstructor;\n\n/**\n * Type constructors for primitive types that can be deserialized\n * (excludes Symbol which cannot be deserialized from JSON)\n */\nexport type PrimitiveConstructor =\n  | StringConstructor\n  | NumberConstructor\n  | BooleanConstructor\n  | BigIntConstructor\n  | DateConstructor;\n\nexport type CtorLike<T> = AnyCtor<T> | BuiltinCtors;\n\nexport type InstanceOfCtorLike<C> = C extends StringConstructor\n  ? string\n  : C extends NumberConstructor\n    ? number\n    : C extends BooleanConstructor\n      ? boolean\n      : C extends BigIntConstructor\n        ? bigint\n        : C extends SymbolConstructor\n          ? symbol\n          : C extends DateConstructor\n            ? Date\n            : C extends AnyCtor<infer T>\n              ? T\n              : never;\n\n/**\n * Options for the Property decorator\n */\nexport interface PropertyOptions<\n  T = any,\n  C extends CtorLike<T> = AnyCtor<T> | BuiltinCtors,\n> {\n  /**\n   * Custom equality comparison function for this property\n   * @param a - First value to compare\n   * @param b - Second value to compare\n   * @returns true if values are equal, false otherwise\n   */\n  equals?: (a: InstanceOfCtorLike<C>, b: InstanceOfCtorLike<C>) => boolean;\n\n  /**\n   * Type constructor for this property. Required for EntityUtils.parse() support.\n   * Use a function that returns the type constructor to support forward references.\n   * Not required for discriminated entity properties nor passthrough properties.\n   * @example\n   * @Property({ type: () => String })\n   * name!: string;\n   *\n   * @Property({ type: () => Address })\n   * address!: Address;\n   */\n  type?: () => C;\n\n  /**\n   * Whether this property is an array. Defaults to false.\n   * When true, the deserializer will map over array elements.\n   * @example\n   * @Property({ type: () => String, array: true })\n   * tags!: string[];\n   */\n  array?: boolean;\n\n  /**\n   * Whether this property is optional. Defaults to false.\n   * When true, the property can be undefined or null.\n   * When false, the property must be present and not null/undefined.\n   * @example\n   * @Property({ type: () => String, optional: true })\n   * nickname?: string;\n   */\n  optional?: boolean;\n\n  /**\n   * Whether the array can contain null/undefined elements. Defaults to false.\n   * Only applicable when array is true.\n   * When false (default), null/undefined elements will cause an error.\n   * When true, null/undefined elements are allowed in the array.\n   * @example\n   * @Property({ type: () => String, array: true, sparse: true })\n   * tags!: (string | null)[];\n   */\n  sparse?: boolean;\n\n  /**\n   * Whether to bypass type validation and pass values through as-is.\n   * Use this for generic types like Record<string, unknown> or any.\n   * When true, no type checking or transformation is performed.\n   * Also bypasses any custom serialize/deserialize callbacks.\n   * @example\n   * @Property({ passthrough: true })\n   * metadata!: Record<string, unknown>;\n   */\n  passthrough?: boolean;\n\n  /**\n   * Whether to prevent this property from being updated via EntityUtils.update().\n   * When true, this property cannot be modified through update operations.\n   * Defaults to false, allowing the property to be updated.\n   * @example\n   * @Property({ type: () => String, preventUpdates: true })\n   * id!: string; // This property cannot be updated\n   */\n  preventUpdates?: boolean;\n\n  /**\n   * Default value for the property when not provided during deserialization.\n   * Can be a static value or a function that returns the default value.\n   * The function can be async and return a Promise.\n   * @example\n   * @Property({ type: () => String, default: 'N/A' })\n   * nickname?: string;\n   *\n   * @Property({ type: () => Date, default: () => new Date() })\n   * createdAt!: Date;\n   *\n   * @Property({ type: () => String, default: async () => await fetchDefaultValue() })\n   * value!: string;\n   */\n  default?:\n    | InstanceOfCtorLike<C>\n    | (() => InstanceOfCtorLike<C> | Promise<InstanceOfCtorLike<C>>);\n\n  /**\n   * Custom serialization function to convert the property value to JSON-compatible format.\n   * Must be paired with deserialize - both must be defined together or both omitted.\n   * Not used when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => MyClass,\n   *   serialize: (value) => ({ data: value.toData() }),\n   *   deserialize: (json) => MyClass.fromData(json.data)\n   * })\n   * myProperty!: MyClass;\n   */\n  serialize?: (value: InstanceOfCtorLike<C>) => unknown;\n\n  /**\n   * Custom deserialization function to convert JSON data back to the property type.\n   * Must be paired with serialize - both must be defined together or both omitted.\n   * Not used when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => MyClass,\n   *   serialize: (value) => ({ data: value.toData() }),\n   *   deserialize: (json) => MyClass.fromData(json.data)\n   * })\n   * myProperty!: MyClass;\n   */\n  deserialize?: (serialized: unknown) => InstanceOfCtorLike<C>;\n\n  /**\n   * Array of validator functions for this property.\n   * Each validator receives the property value and validation context.\n   * Empty array means validation passed.\n   * If the property is an array (array: true), these validators will run against each item.\n   * Use arrayValidators instead to validate the array as a whole.\n   * If passthrough is true, validators will run against the raw value.\n   * @example\n   * @Property({\n   *   type: () => String,\n   *   validators: [\n   *     (value, { createProblem }) =>\n   *       value.length > 10 ? [createProblem('Too long')] : []\n   *   ]\n   * })\n   * name!: string;\n   */\n  validators?: PropertyValidator<InstanceOfCtorLike<C>>[];\n\n  /**\n   * Array of validator functions for this property when it is an array.\n   * Each validator receives the array value and validation context.\n   * Empty array means validation passed.\n   * Only applicable when array is true.\n   * Not applicable when passthrough is true.\n   * @example\n   * @Property({\n   *   type: () => Number,\n   *   array: true,\n   *   arrayValidators: [\n   *     (value, { createProblem }) =>\n   *       value.length === 0 ? [createProblem('Array cannot be empty')] : []\n   *   ]\n   * })\n   * scores!: number[];\n   */\n  arrayValidators?: PropertyValidator<InstanceOfCtorLike<C>[]>[];\n\n  /**\n   * Indicates this property uses discriminated entity types.\n   * The discriminator property name (e.g., '__type') is used to determine the entity type at runtime.\n   * When true, serialization will include the discriminator inline with the entity.\n   * During deserialization, the discriminator value is used to lookup the entity class in EntityRegistry.\n   * @example\n   * @DiscriminatedEntityProperty({ discriminatorProperty: '__type' })\n   * item!: BaseItem; // Could be ItemA or ItemB at runtime\n   */\n  discriminated?: boolean;\n\n  /**\n   * The property name to use as the discriminator for discriminated entity properties.\n   * Defaults to '__type' if not specified.\n   * Only applicable when discriminated is true.\n   * @example\n   * @DiscriminatedEntityProperty({ discriminatorProperty: 'entityType' })\n   * item!: BaseItem;\n   */\n  discriminatorProperty?: string;\n\n  /**\n   * Indicates this property is a polymorphic discriminator.\n   * The property value determines which subclass variant to instantiate during parsing.\n   * Used for class hierarchies where the discriminator is part of the class definition.\n   * @example\n   * @PolymorphicProperty(SchemaPropertyType)\n   * type!: SchemaPropertyType;\n   */\n  polymorphicDiscriminator?: boolean;\n\n  /**\n   * The enum or union type for the polymorphic discriminator.\n   * Used for validation and schema generation (e.g., Zod enums).\n   * @example\n   * @PolymorphicProperty(SchemaPropertyType)\n   * type!: SchemaPropertyType;\n   */\n  polymorphicEnumType?: any;\n}\n\n/**\n * A validator function for a property.\n * The validator receives the value and returns Problems with property paths relative to the value.\n * Can be synchronous or asynchronous.\n * The calling code will prepend the actual property key to all returned problems.\n *\n * @param data - Object containing the value to validate\n * @param data.value - The value to validate\n * @returns Array of Problems (empty if valid) or Promise resolving to Problems.\n *          Problems should have empty property for the value itself,\n *          or relative paths for nested properties (e.g., 'name', '[0]', 'address.street')\n *\n * @example\n * ```typescript\n * // Synchronous validator\n * (({ value }) =>\n *   value.length < 3 ? [new Problem({ property: '', message: 'Too short' })] : [])\n *\n * // Asynchronous validator\n * async ({ value }) => {\n *   const exists = await checkDatabase(value);\n *   return exists ? [] : [new Problem({ property: '', message: 'Not found' })];\n * }\n * ```\n */\nexport type PropertyValidator<T> = (data: {\n  value: T;\n}) => Problem[] | Promise<Problem[]>;\n\n/**\n * A validator function for an entity.\n * Can be synchronous or asynchronous.\n * @param instance - The entity instance to validate\n * @returns Array of Problems (empty if valid) or Promise resolving to Problems\n */\nexport type EntityValidatorFn<T = any> = (\n  instance: T,\n) => Problem[] | Promise<Problem[]>;\n\nexport interface Type<T = any> extends Function {\n  new (...args: any[]): T;\n}\n\nexport type EntityDIToken<T = any> =\n  | string\n  | symbol\n  | Function\n  | AnyCtor<T>\n  | Type<T>;\n\nexport type EntityDIProvider<T = any> =\n  | {\n      provide: EntityDIToken<T>;\n      useValue?: T;\n      useFactory?: never;\n    }\n  | {\n      provide: EntityDIToken<T>;\n      useValue?: never;\n      useFactory?: () => T | Promise<T>;\n    };\n\nexport type EntityDIFallbackFn = (token: EntityDIToken) => Promise<any>;\n\n/**\n * Generic type for safe operation results that can succeed or fail\n * @template T - The data type on success\n */\nexport type SafeOperationResult<T> = Promise<\n  | { success: true; data: T; problems: Problem[] }\n  | { success: false; data: undefined; problems: Problem[] }\n>;\n\nexport type ParseOptions = { strict?: boolean };\n"],"names":["PROPERTY_METADATA_KEY","Symbol","PROPERTY_OPTIONS_METADATA_KEY","ENTITY_METADATA_KEY","ENTITY_OPTIONS_METADATA_KEY","ENTITY_VALIDATOR_METADATA_KEY","POLYMORPHIC_PROPERTY_METADATA_KEY","POLYMORPHIC_VARIANT_METADATA_KEY","INJECTED_PROPERTY_METADATA_KEY","INJECTED_PROPERTY_OPTIONS_METADATA_KEY"],"mappings":"AAAA,6DAA6D,GAC7D,qDAAqD,GACrD,6DAA6D,GAG7D;;CAEC,GACD,OAAO,MAAMA,wBAAwBC,OAAO,qBAAqB;AAEjE;;CAEC,GACD,OAAO,MAAMC,gCAAgCD,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAME,sBAAsBF,OAAO,mBAAmB;AAE7D;;CAEC,GACD,OAAO,MAAMG,8BAA8BH,OAAO,2BAA2B;AAE7E;;CAEC,GACD,OAAO,MAAMI,gCAAgCJ,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAMK,oCAAoCL,OAC/C,iCACA;AAEF;;CAEC,GACD,OAAO,MAAMM,mCAAmCN,OAC9C,gCACA;AAEF;;CAEC,GACD,OAAO,MAAMO,iCAAiCP,OAC5C,8BACA;AAEF;;CAEC,GACD,OAAO,MAAMQ,yCAAyCR,OACpD,sCACA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtpaulino/entity",
-  "version": "0.24.2",
+  "version": "0.25.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",