@rtpaulino/entity 0.11.0 → 0.12.0

package/README.md

@@ -1 +1,327 @@
 # @rtpaulino/entity
+
+A TypeScript entity framework with decorators for metadata-driven serialization and deserialization.
+
+## Features
+
+- **Type-safe decorators** for entity properties
+- **Serialization** via `EntityUtils.toJSON()`
+- **Deserialization** via `EntityUtils.parse()`
+- **Helper decorators** for common types (String, Number, Boolean, Date, BigInt, Entity, Array)
+- **Nested entities** with automatic recursive handling
+- **Optional properties** with null/undefined support
+- **Sparse arrays** for arrays with null/undefined elements
+- **Passthrough mode** for generic types like `Record<string, unknown>`
+
+## Installation
+
+```bash
+npm install @rtpaulino/entity reflect-metadata
+```
+
+Make sure to enable decorators in your `tsconfig.json`:
+
+```json
+{
+  "compilerOptions": {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+}
+```
+
+## Basic Usage
+
+```typescript
+import 'reflect-metadata';
+import {
+  Entity,
+  StringProperty,
+  NumberProperty,
+  EntityUtils,
+} from '@rtpaulino/entity';
+
+@Entity()
+class User {
+  @StringProperty()
+  name!: string;
+
+  @NumberProperty()
+  age!: number;
+}
+
+// Serialization
+const user = new User();
+user.name = 'Alice';
+user.age = 30;
+
+const json = EntityUtils.toJSON(user);
+// { name: 'Alice', age: 30 }
+
+// Deserialization
+const parsed = EntityUtils.parse(User, json);
+// parsed is a User instance with name='Alice' and age=30
+```
+
+## Property Decorators
+
+### Basic Types
+
+```typescript
+@Entity()
+class Example {
+  @StringProperty()
+  text!: string;
+
+  @NumberProperty()
+  count!: number;
+
+  @BooleanProperty()
+  active!: boolean;
+
+  @DateProperty()
+  createdAt!: Date;
+
+  @BigIntProperty()
+  largeNumber!: bigint;
+}
+```
+
+### Optional Properties
+
+Use `optional: true` to allow `null` or `undefined`:
+
+```typescript
+@Entity()
+class User {
+  @StringProperty()
+  name!: string;
+
+  @StringProperty({ optional: true })
+  email?: string | null;
+}
+```
+
+### Nested Entities
+
+```typescript
+@Entity()
+class Address {
+  @StringProperty()
+  city!: string;
+
+  @StringProperty()
+  country!: string;
+}
+
+@Entity()
+class User {
+  @StringProperty()
+  name!: string;
+
+  @EntityProperty(() => Address)
+  address!: Address;
+}
+```
+
+### Arrays
+
+```typescript
+@Entity()
+class Team {
+  @ArrayProperty(() => String)
+  members!: string[];
+
+  @ArrayProperty(() => Number)
+  scores!: number[];
+}
+```
+
+### Sparse Arrays
+
+Use `sparse: true` to allow `null` or `undefined` elements in arrays:
+
+```typescript
+@Entity()
+class Data {
+  @ArrayProperty(() => String, { sparse: true })
+  values!: (string | null)[];
+}
+
+const data = new Data();
+data.values = ['a', null, 'b', undefined, 'c'];
+
+const json = EntityUtils.toJSON(data);
+// { values: ['a', null, 'b', null, 'c'] }
+
+const parsed = EntityUtils.parse(Data, json);
+// parsed.values is ['a', null, 'b', null, 'c']
+```
+
+### Passthrough for Generic Types
+
+By default, the library throws errors for unknown types to prevent accidental misuse. Use `@PassthroughProperty()` decorator or `passthrough: true` option to explicitly handle generic types like `Record<string, unknown>`, `any`, or custom objects:
+
+```typescript
+@Entity()
+class Config {
+  @StringProperty()
+  name!: string;
+
+  @PassthroughProperty()
+  metadata!: Record<string, unknown>;
+
+  @PassthroughProperty()
+  customData!: any;
+}
+
+const config = new Config();
+config.name = 'MyConfig';
+config.metadata = {
+  version: '1.0.0',
+  tags: ['production', 'stable'],
+  nested: { deeply: { nested: { value: 42 } } },
+};
+
+// Serialization - data passes through as-is
+const json = EntityUtils.toJSON(config);
+
+// Deserialization - data passes through as-is
+const parsed = EntityUtils.parse(Config, json);
+// parsed.metadata is exactly what was in the JSON
+```
+
+**Important:** Passthrough cannot be combined with `array`, `optional`, or `sparse` options. Use `@PassthroughProperty()` for the cleanest API.
+
+**Without passthrough, unknown types throw errors:**
+
+```typescript
+@Entity()
+class BadExample {
+  @Property({ type: () => Symbol }) // Symbol is not supported
+  value!: symbol;
+}
+
+// This will throw:
+// "Property 'value' has unknown type constructor. Supported types are: String, Number, Boolean, Date, BigInt, and @Entity() classes."
+```
+
+## Advanced Patterns
+
+### Arrays of Entities
+
+```typescript
+@Entity()
+class Comment {
+  @StringProperty()
+  text!: string;
+
+  @DateProperty()
+  createdAt!: Date;
+}
+
+@Entity()
+class Post {
+  @StringProperty()
+  title!: string;
+
+  @ArrayProperty(() => Comment)
+  comments!: Comment[];
+}
+```
+
+### Complex Nested Structures
+
+```typescript
+@Entity()
+class Organization {
+  @StringProperty()
+  name!: string;
+
+  @ArrayProperty(() => User)
+  admins!: User[];
+
+  @Property({ passthrough: true })
+  settings!: Record<string, unknown>;
+}
+```
+
+## API Reference
+
+### `EntityUtils.toJSON(entity)`
+
+Serializes an entity to a plain JavaScript object.
+
+- Throws error for properties with unknown types (unless `passthrough: true`)
+- Handles nested entities recursively
+- Converts Date to ISO string, BigInt to string
+- Preserves null/undefined for optional properties
+
+### `EntityUtils.parse<T>(entityClass, plainObject)`
+
+Deserializes a plain object to an entity instance.
+
+- Validates all required properties are present
+- Validates property types match metadata
+- Throws error for unknown types (unless `passthrough: true`)
+- Handles nested entities recursively
+- Converts ISO strings back to Date, strings back to BigInt
+
+### Property Options
+
+The `@Property()` decorator requires configuration options. Available options are:
+
+- `type: () => any` - **Required.** Type constructor for the property
+- `array?: boolean` - Whether the property is an array
+- `optional?: boolean` - Allow null/undefined values
+- `sparse?: boolean` - Allow null/undefined in array elements (requires `array: true`)
+- `passthrough?: boolean` - Bypass type validation for generic types (cannot be combined with array, optional, or sparse)
+- `equals?: (a, b) => boolean` - Custom equality function for this property
+
+**Note:** Use helper decorators like `@StringProperty()`, `@PassthroughProperty()`, etc. for cleaner, more readable code. These helpers automatically provide the required `type` parameter.
+
+## Error Handling
+
+The library validates configuration at decorator time and throws descriptive errors for common mistakes:
+
+```typescript
+// Missing required property
+EntityUtils.parse(User, {});
+// Error: Property 'name' is required but missing from input
+
+// Null/undefined on required property
+EntityUtils.parse(User, { name: null, age: 30 });
+// Error: Property 'name' cannot be null or undefined
+
+// Sparse without array (fails at decorator time)
+@Property({ type: () => String, sparse: true }) // Missing array: true
+values!: string[];
+// Error: Property 'values' has sparse: true but array is not true
+
+// Passthrough combined with other options (fails at decorator time)
+@Property({ type: () => Object, passthrough: true, array: true })
+data!: any;
+// Error: Property 'data' has passthrough: true and array: true. Passthrough cannot be combined with array
+
+// Unknown type without passthrough
+@Property({ type: () => WeakMap })
+map!: WeakMap<any, any>;
+// Error: Property 'map' has unknown type constructor
+```
+
+## TypeScript Integration
+
+All methods are fully typed:
+
+```typescript
+const user = EntityUtils.parse(User, json); // user is typed as User
+const json = EntityUtils.toJSON(user); // json is Record<string, unknown>
+```
+
+## License
+
+MIT
+
+```
+
+```

package/dist/lib/entity-utils.d.ts

@@ -31,5 +31,103 @@ export declare class EntityUtils {
         newValue: unknown;
     }[];
     static changes<T extends object>(oldEntity: T, newEntity: T): Partial<T>;
+    /**
+     * Serializes an entity to a plain object, converting only properties decorated with @Property()
+     *
+     * @param entity - The entity instance to serialize
+     * @returns A plain object containing only the serialized decorated properties
+     *
+     * @remarks
+     * Serialization rules:
+     * - Only properties decorated with @Property() are included
+     * - If a property has a custom toJSON() method, it will be used
+     * - Nested entities are recursively serialized using EntityUtils.toJSON()
+     * - Arrays are mapped with toJSON() applied to each element
+     * - Date objects are serialized to ISO strings
+     * - bigint values are serialized to strings
+     * - undefined values are excluded from the output
+     * - null values are included in the output
+     * - Circular references are not supported (will cause stack overflow)
+     *
+     * @example
+     * ```typescript
+     * @Entity()
+     * class Address {
+     *   @Property() street: string;
+     *   @Property() city: string;
+     * }
+     *
+     * @Entity()
+     * class User {
+     *   @Property() name: string;
+     *   @Property() address: Address;
+     *   @Property() createdAt: Date;
+     *   undecorated: string; // Will not be serialized
+     * }
+     *
+     * const user = new User();
+     * user.name = 'John';
+     * user.address = new Address();
+     * user.address.street = '123 Main St';
+     * user.address.city = 'Boston';
+     * user.createdAt = new Date('2024-01-01');
+     * user.undecorated = 'ignored';
+     *
+     * const json = EntityUtils.toJSON(user);
+     * // {
+     * //   name: 'John',
+     * //   address: { street: '123 Main St', city: 'Boston' },
+     * //   createdAt: '2024-01-01T00:00:00.000Z'
+     * // }
+     * ```
+     */
+    static toJSON<T extends object>(entity: T): Record<string, unknown>;
+    /**
+     * Serializes a single value according to the toJSON rules
+     * @private
+     */
+    private static serializeValue;
+    /**
+     * Deserializes a plain object to an entity instance
+     *
+     * @param entityClass - The entity class constructor
+     * @param plainObject - The plain object to deserialize
+     * @returns A new instance of the entity with deserialized values
+     *
+     * @remarks
+     * Deserialization rules:
+     * - All @Property() decorators must include type metadata for parse() to work
+     * - Properties without type metadata will throw an error
+     * - Required properties (optional !== true) must be present and not null/undefined
+     * - Optional properties (optional === true) can be undefined or null
+     * - Arrays are supported with the array: true option
+     * - Nested entities are recursively deserialized
+     * - Type conversion is strict (no coercion)
+     *
+     * @example
+     * ```typescript
+     * @Entity()
+     * class User {
+     *   @Property({ type: () => String }) name!: string;
+     *   @Property({ type: () => Number }) age!: number;
+     *   @Property({ type: () => String, optional: true }) email?: string;
+     * }
+     *
+     * const json = { name: 'John', age: 30 };
+     * const user = EntityUtils.parse(User, json);
+     * // user is a properly typed User instance
+     * ```
+     */
+    static parse<T extends object>(entityClass: new () => T, plainObject: Record<string, unknown>): T;
+    /**
+     * Deserializes a single value according to the type metadata
+     * @private
+     */
+    private static deserializeValue;
+    /**
+     * Deserializes a single non-array value
+     * @private
+     */
+    private static deserializeSingleValue;
 }
 //# sourceMappingURL=entity-utils.d.ts.map

package/dist/lib/entity-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"entity-utils.d.ts","sourceRoot":"","sources":["../../src/lib/entity-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM;IAmB5C,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAQhD,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAoChD,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,eAAe,GAAG,SAAS;IA8B9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO;IA2B9C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,EAC1B,SAAS,EAAE,CAAC,EACZ,SAAS,EAAE,CAAC,GACX;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAAE;IAoC/D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;CAYzE"}
+{"version":3,"file":"entity-utils.d.ts","sourceRoot":"","sources":["../../src/lib/entity-utils.ts"],"names":[],"mappings":"AACA,OAAO,EAIL,eAAe,EAChB,MAAM,YAAY,CAAC;AAGpB,qBAAa,WAAW;IACtB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,MAAM;IAmB5C,MAAM,CAAC,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO;IAQhD,MAAM,CAAC,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE;IAoChD,MAAM,CAAC,kBAAkB,CACvB,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,eAAe,GAAG,SAAS;IA8B9B,MAAM,CAAC,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO;IA2B9C,MAAM,CAAC,IAAI,CAAC,CAAC,SAAS,MAAM,EAC1B,SAAS,EAAE,CAAC,EACZ,SAAS,EAAE,CAAC,GACX;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,EAAE;IAoC/D,MAAM,CAAC,OAAO,CAAC,CAAC,SAAS,MAAM,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAaxE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAmBnE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,cAAc;IAsD7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,KAAK,CAAC,CAAC,SAAS,MAAM,EAC3B,WAAW,EAAE,UAAU,CAAC,EACxB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,CAAC;IA6CJ;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,gBAAgB;IA4C/B;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,sBAAsB;CAoFtC"}

package/dist/lib/entity-utils.js

@@ -1,4 +1,4 @@
-import { ENTITY_METADATA_KEY, PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
+/* eslint-disable @typescript-eslint/no-explicit-any */ import { ENTITY_METADATA_KEY, PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
 import { isEqualWith } from 'lodash-es';
 export class EntityUtils {
     /**
@@ -144,6 +144,255 @@ export class EntityUtils {
             return acc;
         }, {});
     }
+    /**
+   * Serializes an entity to a plain object, converting only properties decorated with @Property()
+   *
+   * @param entity - The entity instance to serialize
+   * @returns A plain object containing only the serialized decorated properties
+   *
+   * @remarks
+   * Serialization rules:
+   * - Only properties decorated with @Property() are included
+   * - If a property has a custom toJSON() method, it will be used
+   * - Nested entities are recursively serialized using EntityUtils.toJSON()
+   * - Arrays are mapped with toJSON() applied to each element
+   * - Date objects are serialized to ISO strings
+   * - bigint values are serialized to strings
+   * - undefined values are excluded from the output
+   * - null values are included in the output
+   * - Circular references are not supported (will cause stack overflow)
+   *
+   * @example
+   * ```typescript
+   * @Entity()
+   * class Address {
+   *   @Property() street: string;
+   *   @Property() city: string;
+   * }
+   *
+   * @Entity()
+   * class User {
+   *   @Property() name: string;
+   *   @Property() address: Address;
+   *   @Property() createdAt: Date;
+   *   undecorated: string; // Will not be serialized
+   * }
+   *
+   * const user = new User();
+   * user.name = 'John';
+   * user.address = new Address();
+   * user.address.street = '123 Main St';
+   * user.address.city = 'Boston';
+   * user.createdAt = new Date('2024-01-01');
+   * user.undecorated = 'ignored';
+   *
+   * const json = EntityUtils.toJSON(user);
+   * // {
+   * //   name: 'John',
+   * //   address: { street: '123 Main St', city: 'Boston' },
+   * //   createdAt: '2024-01-01T00:00:00.000Z'
+   * // }
+   * ```
+   */ static toJSON(entity) {
+        const result = {};
+        const keys = this.getPropertyKeys(entity);
+        for (const key of keys){
+            const value = entity[key];
+            // Skip undefined values
+            if (value === undefined) {
+                continue;
+            }
+            const options = this.getPropertyOptions(entity, key);
+            result[key] = this.serializeValue(value, options);
+        }
+        return result;
+    }
+    /**
+   * Serializes a single value according to the toJSON rules
+   * @private
+   */ static serializeValue(value, options) {
+        if (value === null) {
+            return null;
+        }
+        if (value === undefined) {
+            return undefined;
+        }
+        const passthrough = options?.passthrough === true;
+        if (passthrough) {
+            return value;
+        }
+        if (Array.isArray(value)) {
+            if (options?.serialize) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                return value.map((item)=>options.serialize(item));
+            }
+            return value.map((item)=>this.serializeValue(item));
+        }
+        if (options?.serialize) {
+            return options.serialize(value);
+        }
+        if (value instanceof Date) {
+            return value.toISOString();
+        }
+        if (typeof value === 'bigint') {
+            return value.toString();
+        }
+        if (this.isEntity(value)) {
+            return this.toJSON(value);
+        }
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return value;
+        }
+        throw new Error(`Cannot serialize value of type '${typeof value}'. Use passthrough: true in @Property() to explicitly allow serialization of unknown types.`);
+    }
+    /**
+   * Deserializes a plain object to an entity instance
+   *
+   * @param entityClass - The entity class constructor
+   * @param plainObject - The plain object to deserialize
+   * @returns A new instance of the entity with deserialized values
+   *
+   * @remarks
+   * Deserialization rules:
+   * - All @Property() decorators must include type metadata for parse() to work
+   * - Properties without type metadata will throw an error
+   * - Required properties (optional !== true) must be present and not null/undefined
+   * - Optional properties (optional === true) can be undefined or null
+   * - Arrays are supported with the array: true option
+   * - Nested entities are recursively deserialized
+   * - Type conversion is strict (no coercion)
+   *
+   * @example
+   * ```typescript
+   * @Entity()
+   * class User {
+   *   @Property({ type: () => String }) name!: string;
+   *   @Property({ type: () => Number }) age!: number;
+   *   @Property({ type: () => String, optional: true }) email?: string;
+   * }
+   *
+   * const json = { name: 'John', age: 30 };
+   * const user = EntityUtils.parse(User, json);
+   * // user is a properly typed User instance
+   * ```
+   */ static parse(entityClass, plainObject) {
+        const instance = new entityClass();
+        const keys = this.getPropertyKeys(instance);
+        for (const key of keys){
+            const options = this.getPropertyOptions(instance, key);
+            if (!options) {
+                throw new Error(`Property '${key}' has no metadata. This should not happen if @Property() was used correctly.`);
+            }
+            if (options.passthrough === true) {
+                const value = plainObject[key];
+                instance[key] = value;
+                continue;
+            }
+            const value = plainObject[key];
+            const isOptional = options.optional === true;
+            if (!(key in plainObject)) {
+                if (!isOptional) {
+                    throw new Error(`Property '${key}' is required but missing from input`);
+                }
+                continue;
+            }
+            if (value === null || value === undefined) {
+                if (!isOptional) {
+                    throw new Error(`Property '${key}' cannot be null or undefined`);
+                }
+                instance[key] = value;
+                continue;
+            }
+            instance[key] = this.deserializeValue(value, options, key);
+        }
+        return instance;
+    }
+    /**
+   * Deserializes a single value according to the type metadata
+   * @private
+   */ static deserializeValue(value, options, propertyKey) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+        const typeConstructor = options.type();
+        const isArray = options.array === true;
+        const isSparse = options.sparse === true;
+        if (isArray) {
+            if (!Array.isArray(value)) {
+                throw new Error(`Property '${propertyKey}' expects an array but received ${typeof value}`);
+            }
+            return value.map((item, index)=>{
+                if (item === null || item === undefined) {
+                    if (!isSparse) {
+                        throw new Error(`Property '${propertyKey}[${index}]' cannot be null or undefined. Use sparse: true to allow null/undefined elements in arrays.`);
+                    }
+                    return item;
+                }
+                if (options.deserialize) {
+                    return options.deserialize(item);
+                }
+                return this.deserializeSingleValue(item, typeConstructor, `${propertyKey}[${index}]`);
+            });
+        }
+        if (options.deserialize) {
+            return options.deserialize(value);
+        }
+        return this.deserializeSingleValue(value, typeConstructor, propertyKey);
+    }
+    /**
+   * Deserializes a single non-array value
+   * @private
+   */ static deserializeSingleValue(value, typeConstructor, propertyKey) {
+        if (typeConstructor === String) {
+            if (typeof value !== 'string') {
+                throw new Error(`Property '${propertyKey}' expects a string but received ${typeof value}`);
+            }
+            return value;
+        }
+        if (typeConstructor === Number) {
+            if (typeof value !== 'number') {
+                throw new Error(`Property '${propertyKey}' expects a number but received ${typeof value}`);
+            }
+            return value;
+        }
+        if (typeConstructor === Boolean) {
+            if (typeof value !== 'boolean') {
+                throw new Error(`Property '${propertyKey}' expects a boolean but received ${typeof value}`);
+            }
+            return value;
+        }
+        if (typeConstructor === BigInt) {
+            if (typeof value === 'bigint') {
+                return value;
+            }
+            if (typeof value === 'string') {
+                try {
+                    return BigInt(value);
+                } catch  {
+                    throw new Error(`Property '${propertyKey}' cannot parse '${value}' as BigInt`);
+                }
+            }
+            throw new Error(`Property '${propertyKey}' expects a bigint or string but received ${typeof value}`);
+        }
+        if (typeConstructor === Date) {
+            if (value instanceof Date) {
+                return value;
+            }
+            if (typeof value === 'string') {
+                const date = new Date(value);
+                if (isNaN(date.getTime())) {
+                    throw new Error(`Property '${propertyKey}' cannot parse '${value}' as Date`);
+                }
+                return date;
+            }
+            throw new Error(`Property '${propertyKey}' expects a Date or ISO string but received ${typeof value}`);
+        }
+        if (this.isEntity(typeConstructor)) {
+            if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+                throw new Error(`Property '${propertyKey}' expects an object but received ${typeof value}`);
+            }
+            return this.parse(typeConstructor, value);
+        }
+        throw new Error(`Property '${propertyKey}' has unknown type constructor. Supported types are: String, Number, Boolean, Date, BigInt, and @Entity() classes. Use passthrough: true to explicitly allow unknown types.`);
+    }
 }
 
 //# sourceMappingURL=entity-utils.js.map

package/dist/lib/entity-utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/entity-utils.ts"],"sourcesContent":["import {\n  ENTITY_METADATA_KEY,\n  PROPERTY_METADATA_KEY,\n  PROPERTY_OPTIONS_METADATA_KEY,\n  PropertyOptions,\n} from './types.js';\nimport { isEqualWith } from 'lodash-es';\n\nexport class EntityUtils {\n  /**\n   * Checks if a given object is an instance of a class decorated with @Entity()\n   * or if the provided value is an entity class itself\n   *\n   * @param obj - The object or class to check\n   * @returns true if the object is an entity instance or entity class, false otherwise\n   *\n   * @example\n   * ```typescript\n   * @Entity()\n   * class User {\n   *   name: string;\n   * }\n   *\n   * const user = new User();\n   * console.log(EntityUtils.isEntity(user)); // true\n   * console.log(EntityUtils.isEntity(User)); // true\n   * console.log(EntityUtils.isEntity({})); // false\n   * ```\n   */\n  static isEntity(obj: unknown): obj is object {\n    if (obj == null) {\n      return false;\n    }\n\n    // Check if obj is a constructor function (class)\n    if (typeof obj === 'function') {\n      return Reflect.hasMetadata(ENTITY_METADATA_KEY, obj);\n    }\n\n    // Check if obj is an object instance\n    if (typeof obj !== 'object' || Array.isArray(obj)) {\n      return false;\n    }\n\n    const constructor = Object.getPrototypeOf(obj).constructor;\n    return Reflect.hasMetadata(ENTITY_METADATA_KEY, constructor);\n  }\n\n  static sameEntity(a: object, b: object): boolean {\n    if (!this.isEntity(a) || !this.isEntity(b)) {\n      return false;\n    }\n\n    return Object.getPrototypeOf(a) === Object.getPrototypeOf(b);\n  }\n\n  static getPropertyKeys(target: object): string[] {\n    // Determine if we're dealing with a prototype or an instance\n    let currentProto: any;\n\n    // Check if target is a prototype by checking if it has a constructor property\n    // and if target === target.constructor.prototype\n    if (target.constructor && target === target.constructor.prototype) {\n      // target is already a prototype\n      currentProto = target;\n    } else {\n      // target is an instance, get its prototype\n      currentProto = Object.getPrototypeOf(target);\n    }\n\n    const keys: string[] = [];\n    const seen = new Set<string>();\n\n    // Walk the prototype chain to collect all inherited properties\n    while (currentProto && currentProto !== Object.prototype) {\n      // Use getOwnMetadata to only get metadata directly on this prototype\n      const protoKeys: string[] =\n        Reflect.getOwnMetadata(PROPERTY_METADATA_KEY, currentProto) || [];\n\n      for (const key of protoKeys) {\n        if (!seen.has(key)) {\n          seen.add(key);\n          keys.push(key);\n        }\n      }\n\n      currentProto = Object.getPrototypeOf(currentProto);\n    }\n\n    return keys;\n  }\n\n  static getPropertyOptions(\n    target: object,\n    propertyKey: string,\n  ): PropertyOptions | undefined {\n    // Determine if we're dealing with a prototype or an instance\n    let currentProto: any;\n\n    // Check if target is a prototype by checking if it has a constructor property\n    // and if target === target.constructor.prototype\n    if (target.constructor && target === target.constructor.prototype) {\n      // target is already a prototype\n      currentProto = target;\n    } else {\n      // target is an instance, get its prototype\n      currentProto = Object.getPrototypeOf(target);\n    }\n\n    // Walk the prototype chain to find the property options\n    while (currentProto && currentProto !== Object.prototype) {\n      const protoOptions: Record<string, PropertyOptions> =\n        Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, currentProto) ||\n        {};\n\n      if (protoOptions[propertyKey]) {\n        return protoOptions[propertyKey];\n      }\n\n      currentProto = Object.getPrototypeOf(currentProto);\n    }\n\n    return undefined;\n  }\n\n  static equals(a: unknown, b: unknown): boolean {\n    return isEqualWith(a, b, (val1, val2) => {\n      if (this.isEntity(val1)) {\n        if (!this.sameEntity(val1, val2)) {\n          return false;\n        }\n\n        const diff = this.diff(val1, val2);\n\n        return diff.length === 0;\n      } else if (\n        val1 != null &&\n        val2 != null &&\n        typeof val1 === 'object' &&\n        !Array.isArray(val1) &&\n        typeof val2 === 'object' &&\n        !Array.isArray(val2) &&\n        'equals' in val1 &&\n        typeof val1.equals === 'function'\n      ) {\n        return val1.equals(val2);\n      }\n\n      return undefined;\n    });\n  }\n\n  static diff<T extends object>(\n    oldEntity: T,\n    newEntity: T,\n  ): { property: string; oldValue: unknown; newValue: unknown }[] {\n    if (!this.sameEntity(oldEntity, newEntity)) {\n      throw new Error('Entities must be of the same type to compute diff');\n    }\n\n    const diffs: { property: string; oldValue: unknown; newValue: unknown }[] =\n      [];\n\n    const keys = this.getPropertyKeys(oldEntity);\n\n    for (const key of keys) {\n      const oldValue = (oldEntity as any)[key];\n      const newValue = (newEntity as any)[key];\n\n      // Check if there's a custom equals function for this property\n      const propertyOptions = this.getPropertyOptions(oldEntity, key);\n\n      let areEqual: boolean;\n      if (oldValue == null && newValue == null) {\n        areEqual = oldValue === newValue;\n      } else if (oldValue == null || newValue == null) {\n        areEqual = false;\n      } else {\n        areEqual = propertyOptions?.equals\n          ? propertyOptions.equals(oldValue, newValue)\n          : this.equals(oldValue, newValue);\n      }\n\n      if (!areEqual) {\n        diffs.push({ property: key, oldValue, newValue });\n      }\n    }\n\n    return diffs;\n  }\n\n  static changes<T extends object>(oldEntity: T, newEntity: T): Partial<T> {\n    if (!this.sameEntity(oldEntity, newEntity)) {\n      throw new Error('Entities must be of the same type to compute changes');\n    }\n\n    const diff = this.diff(oldEntity, newEntity);\n\n    return diff.reduce((acc, { property, newValue }) => {\n      (acc as any)[property] = newValue;\n      return acc;\n    }, {} as Partial<T>);\n  }\n}\n"],"names":["ENTITY_METADATA_KEY","PROPERTY_METADATA_KEY","PROPERTY_OPTIONS_METADATA_KEY","isEqualWith","EntityUtils","isEntity","obj","Reflect","hasMetadata","Array","isArray","constructor","Object","getPrototypeOf","sameEntity","a","b","getPropertyKeys","target","currentProto","prototype","keys","seen","Set","protoKeys","getOwnMetadata","key","has","add","push","getPropertyOptions","propertyKey","protoOptions","undefined","equals","val1","val2","diff","length","oldEntity","newEntity","Error","diffs","oldValue","newValue","propertyOptions","areEqual","property","changes","reduce","acc"],"mappings":"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"}
+{"version":3,"sources":["../../src/lib/entity-utils.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\nimport {\n  ENTITY_METADATA_KEY,\n  PROPERTY_METADATA_KEY,\n  PROPERTY_OPTIONS_METADATA_KEY,\n  PropertyOptions,\n} from './types.js';\nimport { isEqualWith } from 'lodash-es';\n\nexport class EntityUtils {\n  /**\n   * Checks if a given object is an instance of a class decorated with @Entity()\n   * or if the provided value is an entity class itself\n   *\n   * @param obj - The object or class to check\n   * @returns true if the object is an entity instance or entity class, false otherwise\n   *\n   * @example\n   * ```typescript\n   * @Entity()\n   * class User {\n   *   name: string;\n   * }\n   *\n   * const user = new User();\n   * console.log(EntityUtils.isEntity(user)); // true\n   * console.log(EntityUtils.isEntity(User)); // true\n   * console.log(EntityUtils.isEntity({})); // false\n   * ```\n   */\n  static isEntity(obj: unknown): obj is object {\n    if (obj == null) {\n      return false;\n    }\n\n    // Check if obj is a constructor function (class)\n    if (typeof obj === 'function') {\n      return Reflect.hasMetadata(ENTITY_METADATA_KEY, obj);\n    }\n\n    // Check if obj is an object instance\n    if (typeof obj !== 'object' || Array.isArray(obj)) {\n      return false;\n    }\n\n    const constructor = Object.getPrototypeOf(obj).constructor;\n    return Reflect.hasMetadata(ENTITY_METADATA_KEY, constructor);\n  }\n\n  static sameEntity(a: object, b: object): boolean {\n    if (!this.isEntity(a) || !this.isEntity(b)) {\n      return false;\n    }\n\n    return Object.getPrototypeOf(a) === Object.getPrototypeOf(b);\n  }\n\n  static getPropertyKeys(target: object): string[] {\n    // Determine if we're dealing with a prototype or an instance\n    let currentProto: any;\n\n    // Check if target is a prototype by checking if it has a constructor property\n    // and if target === target.constructor.prototype\n    if (target.constructor && target === target.constructor.prototype) {\n      // target is already a prototype\n      currentProto = target;\n    } else {\n      // target is an instance, get its prototype\n      currentProto = Object.getPrototypeOf(target);\n    }\n\n    const keys: string[] = [];\n    const seen = new Set<string>();\n\n    // Walk the prototype chain to collect all inherited properties\n    while (currentProto && currentProto !== Object.prototype) {\n      // Use getOwnMetadata to only get metadata directly on this prototype\n      const protoKeys: string[] =\n        Reflect.getOwnMetadata(PROPERTY_METADATA_KEY, currentProto) || [];\n\n      for (const key of protoKeys) {\n        if (!seen.has(key)) {\n          seen.add(key);\n          keys.push(key);\n        }\n      }\n\n      currentProto = Object.getPrototypeOf(currentProto);\n    }\n\n    return keys;\n  }\n\n  static getPropertyOptions(\n    target: object,\n    propertyKey: string,\n  ): PropertyOptions | undefined {\n    // Determine if we're dealing with a prototype or an instance\n    let currentProto: any;\n\n    // Check if target is a prototype by checking if it has a constructor property\n    // and if target === target.constructor.prototype\n    if (target.constructor && target === target.constructor.prototype) {\n      // target is already a prototype\n      currentProto = target;\n    } else {\n      // target is an instance, get its prototype\n      currentProto = Object.getPrototypeOf(target);\n    }\n\n    // Walk the prototype chain to find the property options\n    while (currentProto && currentProto !== Object.prototype) {\n      const protoOptions: Record<string, PropertyOptions> =\n        Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, currentProto) ||\n        {};\n\n      if (protoOptions[propertyKey]) {\n        return protoOptions[propertyKey];\n      }\n\n      currentProto = Object.getPrototypeOf(currentProto);\n    }\n\n    return undefined;\n  }\n\n  static equals(a: unknown, b: unknown): boolean {\n    return isEqualWith(a, b, (val1, val2) => {\n      if (this.isEntity(val1)) {\n        if (!this.sameEntity(val1, val2)) {\n          return false;\n        }\n\n        const diff = this.diff(val1, val2);\n\n        return diff.length === 0;\n      } else if (\n        val1 != null &&\n        val2 != null &&\n        typeof val1 === 'object' &&\n        !Array.isArray(val1) &&\n        typeof val2 === 'object' &&\n        !Array.isArray(val2) &&\n        'equals' in val1 &&\n        typeof val1.equals === 'function'\n      ) {\n        return val1.equals(val2);\n      }\n\n      return undefined;\n    });\n  }\n\n  static diff<T extends object>(\n    oldEntity: T,\n    newEntity: T,\n  ): { property: string; oldValue: unknown; newValue: unknown }[] {\n    if (!this.sameEntity(oldEntity, newEntity)) {\n      throw new Error('Entities must be of the same type to compute diff');\n    }\n\n    const diffs: { property: string; oldValue: unknown; newValue: unknown }[] =\n      [];\n\n    const keys = this.getPropertyKeys(oldEntity);\n\n    for (const key of keys) {\n      const oldValue = (oldEntity as any)[key];\n      const newValue = (newEntity as any)[key];\n\n      // Check if there's a custom equals function for this property\n      const propertyOptions = this.getPropertyOptions(oldEntity, key);\n\n      let areEqual: boolean;\n      if (oldValue == null && newValue == null) {\n        areEqual = oldValue === newValue;\n      } else if (oldValue == null || newValue == null) {\n        areEqual = false;\n      } else {\n        areEqual = propertyOptions?.equals\n          ? propertyOptions.equals(oldValue, newValue)\n          : this.equals(oldValue, newValue);\n      }\n\n      if (!areEqual) {\n        diffs.push({ property: key, oldValue, newValue });\n      }\n    }\n\n    return diffs;\n  }\n\n  static changes<T extends object>(oldEntity: T, newEntity: T): Partial<T> {\n    if (!this.sameEntity(oldEntity, newEntity)) {\n      throw new Error('Entities must be of the same type to compute changes');\n    }\n\n    const diff = this.diff(oldEntity, newEntity);\n\n    return diff.reduce((acc, { property, newValue }) => {\n      (acc as any)[property] = newValue;\n      return acc;\n    }, {} as Partial<T>);\n  }\n\n  /**\n   * Serializes an entity to a plain object, converting only properties decorated with @Property()\n   *\n   * @param entity - The entity instance to serialize\n   * @returns A plain object containing only the serialized decorated properties\n   *\n   * @remarks\n   * Serialization rules:\n   * - Only properties decorated with @Property() are included\n   * - If a property has a custom toJSON() method, it will be used\n   * - Nested entities are recursively serialized using EntityUtils.toJSON()\n   * - Arrays are mapped with toJSON() applied to each element\n   * - Date objects are serialized to ISO strings\n   * - bigint values are serialized to strings\n   * - undefined values are excluded from the output\n   * - null values are included in the output\n   * - Circular references are not supported (will cause stack overflow)\n   *\n   * @example\n   * ```typescript\n   * @Entity()\n   * class Address {\n   *   @Property() street: string;\n   *   @Property() city: string;\n   * }\n   *\n   * @Entity()\n   * class User {\n   *   @Property() name: string;\n   *   @Property() address: Address;\n   *   @Property() createdAt: Date;\n   *   undecorated: string; // Will not be serialized\n   * }\n   *\n   * const user = new User();\n   * user.name = 'John';\n   * user.address = new Address();\n   * user.address.street = '123 Main St';\n   * user.address.city = 'Boston';\n   * user.createdAt = new Date('2024-01-01');\n   * user.undecorated = 'ignored';\n   *\n   * const json = EntityUtils.toJSON(user);\n   * // {\n   * //   name: 'John',\n   * //   address: { street: '123 Main St', city: 'Boston' },\n   * //   createdAt: '2024-01-01T00:00:00.000Z'\n   * // }\n   * ```\n   */\n  static toJSON<T extends object>(entity: T): Record<string, unknown> {\n    const result: Record<string, unknown> = {};\n    const keys = this.getPropertyKeys(entity);\n\n    for (const key of keys) {\n      const value = (entity as any)[key];\n\n      // Skip undefined values\n      if (value === undefined) {\n        continue;\n      }\n\n      const options = this.getPropertyOptions(entity, key);\n      result[key] = this.serializeValue(value, options);\n    }\n\n    return result;\n  }\n\n  /**\n   * Serializes a single value according to the toJSON rules\n   * @private\n   */\n  private static serializeValue(\n    value: unknown,\n    options?: PropertyOptions,\n  ): unknown {\n    if (value === null) {\n      return null;\n    }\n\n    if (value === undefined) {\n      return undefined;\n    }\n\n    const passthrough = options?.passthrough === true;\n    if (passthrough) {\n      return value;\n    }\n\n    if (Array.isArray(value)) {\n      if (options?.serialize) {\n        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n        return value.map((item) => options.serialize!(item as any));\n      }\n      return value.map((item) => this.serializeValue(item));\n    }\n\n    if (options?.serialize) {\n      return options.serialize(value as any);\n    }\n\n    if (value instanceof Date) {\n      return value.toISOString();\n    }\n\n    if (typeof value === 'bigint') {\n      return value.toString();\n    }\n\n    if (this.isEntity(value)) {\n      return this.toJSON(value);\n    }\n\n    if (\n      typeof value === 'string' ||\n      typeof value === 'number' ||\n      typeof value === 'boolean'\n    ) {\n      return value;\n    }\n\n    throw new Error(\n      `Cannot serialize value of type '${typeof value}'. Use passthrough: true in @Property() to explicitly allow serialization of unknown types.`,\n    );\n  }\n\n  /**\n   * Deserializes a plain object to an entity instance\n   *\n   * @param entityClass - The entity class constructor\n   * @param plainObject - The plain object to deserialize\n   * @returns A new instance of the entity with deserialized values\n   *\n   * @remarks\n   * Deserialization rules:\n   * - All @Property() decorators must include type metadata for parse() to work\n   * - Properties without type metadata will throw an error\n   * - Required properties (optional !== true) must be present and not null/undefined\n   * - Optional properties (optional === true) can be undefined or null\n   * - Arrays are supported with the array: true option\n   * - Nested entities are recursively deserialized\n   * - Type conversion is strict (no coercion)\n   *\n   * @example\n   * ```typescript\n   * @Entity()\n   * class User {\n   *   @Property({ type: () => String }) name!: string;\n   *   @Property({ type: () => Number }) age!: number;\n   *   @Property({ type: () => String, optional: true }) email?: string;\n   * }\n   *\n   * const json = { name: 'John', age: 30 };\n   * const user = EntityUtils.parse(User, json);\n   * // user is a properly typed User instance\n   * ```\n   */\n  static parse<T extends object>(\n    entityClass: new () => T,\n    plainObject: Record<string, unknown>,\n  ): T {\n    const instance = new entityClass();\n    const keys = this.getPropertyKeys(instance);\n\n    for (const key of keys) {\n      const options = this.getPropertyOptions(instance, key);\n\n      if (!options) {\n        throw new Error(\n          `Property '${key}' has no metadata. This should not happen if @Property() was used correctly.`,\n        );\n      }\n\n      if (options.passthrough === true) {\n        const value = plainObject[key];\n        (instance as any)[key] = value;\n        continue;\n      }\n\n      const value = plainObject[key];\n      const isOptional = options.optional === true;\n\n      if (!(key in plainObject)) {\n        if (!isOptional) {\n          throw new Error(\n            `Property '${key}' is required but missing from input`,\n          );\n        }\n        continue;\n      }\n\n      if (value === null || value === undefined) {\n        if (!isOptional) {\n          throw new Error(`Property '${key}' cannot be null or undefined`);\n        }\n        (instance as any)[key] = value;\n        continue;\n      }\n\n      (instance as any)[key] = this.deserializeValue(value, options, key);\n    }\n\n    return instance;\n  }\n\n  /**\n   * Deserializes a single value according to the type metadata\n   * @private\n   */\n  private static deserializeValue(\n    value: unknown,\n    options: PropertyOptions,\n    propertyKey: string,\n  ): unknown {\n    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion\n    const typeConstructor = options.type!();\n    const isArray = options.array === true;\n    const isSparse = options.sparse === true;\n\n    if (isArray) {\n      if (!Array.isArray(value)) {\n        throw new Error(\n          `Property '${propertyKey}' expects an array but received ${typeof value}`,\n        );\n      }\n\n      return value.map((item, index) => {\n        if (item === null || item === undefined) {\n          if (!isSparse) {\n            throw new Error(\n              `Property '${propertyKey}[${index}]' cannot be null or undefined. Use sparse: true to allow null/undefined elements in arrays.`,\n            );\n          }\n          return item;\n        }\n        if (options.deserialize) {\n          return options.deserialize(item);\n        }\n        return this.deserializeSingleValue(\n          item,\n          typeConstructor,\n          `${propertyKey}[${index}]`,\n        );\n      });\n    }\n\n    if (options.deserialize) {\n      return options.deserialize(value);\n    }\n\n    return this.deserializeSingleValue(value, typeConstructor, propertyKey);\n  }\n\n  /**\n   * Deserializes a single non-array value\n   * @private\n   */\n  private static deserializeSingleValue(\n    value: unknown,\n    typeConstructor: any,\n    propertyKey: string,\n  ): unknown {\n    if (typeConstructor === String) {\n      if (typeof value !== 'string') {\n        throw new Error(\n          `Property '${propertyKey}' expects a string but received ${typeof value}`,\n        );\n      }\n      return value;\n    }\n\n    if (typeConstructor === Number) {\n      if (typeof value !== 'number') {\n        throw new Error(\n          `Property '${propertyKey}' expects a number but received ${typeof value}`,\n        );\n      }\n      return value;\n    }\n\n    if (typeConstructor === Boolean) {\n      if (typeof value !== 'boolean') {\n        throw new Error(\n          `Property '${propertyKey}' expects a boolean but received ${typeof value}`,\n        );\n      }\n      return value;\n    }\n\n    if (typeConstructor === BigInt) {\n      if (typeof value === 'bigint') {\n        return value;\n      }\n      if (typeof value === 'string') {\n        try {\n          return BigInt(value);\n        } catch {\n          throw new Error(\n            `Property '${propertyKey}' cannot parse '${value}' as BigInt`,\n          );\n        }\n      }\n      throw new Error(\n        `Property '${propertyKey}' expects a bigint or string but received ${typeof value}`,\n      );\n    }\n\n    if (typeConstructor === Date) {\n      if (value instanceof Date) {\n        return value;\n      }\n      if (typeof value === 'string') {\n        const date = new Date(value);\n        if (isNaN(date.getTime())) {\n          throw new Error(\n            `Property '${propertyKey}' cannot parse '${value}' as Date`,\n          );\n        }\n        return date;\n      }\n      throw new Error(\n        `Property '${propertyKey}' expects a Date or ISO string but received ${typeof value}`,\n      );\n    }\n\n    if (this.isEntity(typeConstructor)) {\n      if (typeof value !== 'object' || value === null || Array.isArray(value)) {\n        throw new Error(\n          `Property '${propertyKey}' expects an object but received ${typeof value}`,\n        );\n      }\n      return this.parse(\n        typeConstructor as new () => object,\n        value as Record<string, unknown>,\n      );\n    }\n\n    throw new Error(\n      `Property '${propertyKey}' has unknown type constructor. Supported types are: String, Number, Boolean, Date, BigInt, and @Entity() classes. Use passthrough: true to explicitly allow unknown types.`,\n    );\n  }\n}\n"],"names":["ENTITY_METADATA_KEY","PROPERTY_METADATA_KEY","PROPERTY_OPTIONS_METADATA_KEY","isEqualWith","EntityUtils","isEntity","obj","Reflect","hasMetadata","Array","isArray","constructor","Object","getPrototypeOf","sameEntity","a","b","getPropertyKeys","target","currentProto","prototype","keys","seen","Set","protoKeys","getOwnMetadata","key","has","add","push","getPropertyOptions","propertyKey","protoOptions","undefined","equals","val1","val2","diff","length","oldEntity","newEntity","Error","diffs","oldValue","newValue","propertyOptions","areEqual","property","changes","reduce","acc","toJSON","entity","result","value","options","serializeValue","passthrough","serialize","map","item","Date","toISOString","toString","parse","entityClass","plainObject","instance","isOptional","optional","deserializeValue","typeConstructor","type","array","isSparse","sparse","index","deserialize","deserializeSingleValue","String","Number","Boolean","BigInt","date","isNaN","getTime"],"mappings":"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"}

package/dist/lib/property.d.ts

@@ -1,21 +1,124 @@
-import { PropertyOptions } from './types.js';
+import { AnyCtor, type CtorLike, PropertyOptions } from './types.js';
 /**
  * Property decorator that marks class properties with metadata.
  * This decorator can be used to identify and track properties within classes.
  *
- * @param options - Optional configuration for the property
+ * @param options - Configuration for the property (type is required)
  *
  * @example
  * class User {
- *   @Property()
+ *   @Property({ type: () => String })
  *   name: string;
  *
- *   @Property({ equals: (a, b) => a.toLowerCase() === b.toLowerCase() })
+ *   @Property({ type: () => String, equals: (a, b) => a.toLowerCase() === b.toLowerCase() })
  *   email: string;
  *
- *   @Property()
+ *   @Property({ type: () => Number })
  *   age: number;
  * }
  */
-export declare function Property<T = any>(options?: PropertyOptions<T>): PropertyDecorator;
+export declare function Property<T, C extends CtorLike<T>>(options: PropertyOptions<T, C>): PropertyDecorator;
+/**
+ * Helper decorator for string properties
+ * @example
+ * class User {
+ *   @StringProperty()
+ *   name!: string;
+ *
+ *   @StringProperty({ optional: true })
+ *   nickname?: string;
+ * }
+ */
+export declare function StringProperty(options?: Omit<PropertyOptions<string, StringConstructor>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for number properties
+ * @example
+ * class User {
+ *   @NumberProperty()
+ *   age!: number;
+ *
+ *   @NumberProperty({ optional: true })
+ *   score?: number;
+ * }
+ */
+export declare function NumberProperty(options?: Omit<PropertyOptions<number, NumberConstructor>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for boolean properties
+ * @example
+ * class User {
+ *   @BooleanProperty()
+ *   active!: boolean;
+ *
+ *   @BooleanProperty({ optional: true })
+ *   verified?: boolean;
+ * }
+ */
+export declare function BooleanProperty(options?: Omit<PropertyOptions<boolean, BooleanConstructor>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for Date properties
+ * @example
+ * class User {
+ *   @DateProperty()
+ *   createdAt!: Date;
+ *
+ *   @DateProperty({ optional: true })
+ *   deletedAt?: Date;
+ * }
+ */
+export declare function DateProperty(options?: Omit<PropertyOptions<Date, DateConstructor>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for BigInt properties
+ * @example
+ * class User {
+ *   @BigIntProperty()
+ *   id!: bigint;
+ *
+ *   @BigIntProperty({ optional: true })
+ *   balance?: bigint;
+ * }
+ */
+export declare function BigIntProperty(options?: Omit<PropertyOptions<bigint, BigIntConstructor>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for entity properties
+ * @example
+ * class User {
+ *   @EntityProperty(() => Address)
+ *   address!: Address;
+ *
+ *   @EntityProperty(() => Profile, { optional: true })
+ *   profile?: Profile;
+ * }
+ */
+export declare function EntityProperty<T, C extends AnyCtor<T>>(type: () => C, options?: Omit<PropertyOptions<T, C>, 'type'>): PropertyDecorator;
+/**
+ * Helper decorator for array properties
+ * @example
+ * class User {
+ *   @ArrayProperty(() => String)
+ *   tags!: string[];
+ *
+ *   @ArrayProperty(() => Phone)
+ *   phones!: Phone[];
+ *
+ *   @ArrayProperty(() => Number, { optional: true })
+ *   scores?: number[];
+ *
+ *   @ArrayProperty(() => String, { sparse: true })
+ *   sparseList!: (string | null)[];
+ * }
+ */
+export declare function ArrayProperty<T, C extends CtorLike<T>>(type: () => C, options?: Omit<PropertyOptions<T, C>, 'type' | 'array'>): PropertyDecorator;
+/**
+ * Helper decorator for passthrough properties that bypass type validation.
+ * Use this for generic types like Record<string, unknown>, any, or custom objects.
+ * @example
+ * class Config {
+ *   @PassthroughProperty()
+ *   metadata!: Record<string, unknown>;
+ *
+ *   @PassthroughProperty()
+ *   customData!: any;
+ * }
+ */
+export declare function PassthroughProperty(): PropertyDecorator;
 //# sourceMappingURL=property.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../../src/lib/property.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,GAAG,GAAG,EAC9B,OAAO,CAAC,EAAE,eAAe,CAAC,CAAC,CAAC,GAC3B,iBAAiB,CAiCnB"}
+{"version":3,"file":"property.d.ts","sourceRoot":"","sources":["../../src/lib/property.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,OAAO,EACP,KAAK,QAAQ,EAGb,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EAC/C,OAAO,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,GAC7B,iBAAiB,CAqEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,GACjE,iBAAiB,CAEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,GACjE,iBAAiB,CAEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAC7B,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,EAAE,MAAM,CAAC,GACnE,iBAAiB,CAEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAC1B,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,IAAI,EAAE,eAAe,CAAC,EAAE,MAAM,CAAC,GAC7D,iBAAiB,CAEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAAE,MAAM,CAAC,GACjE,iBAAiB,CAEnB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,EACpD,IAAI,EAAE,MAAM,CAAC,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,GAC5C,iBAAiB,CAEnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,EACpD,IAAI,EAAE,MAAM,CAAC,EACb,OAAO,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GACtD,iBAAiB,CAEnB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,mBAAmB,IAAI,iBAAiB,CAGvD"}

package/dist/lib/property.js

@@ -1,42 +1,195 @@
-import { PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
+/* eslint-disable @typescript-eslint/no-wrapper-object-types */ /* eslint-disable @typescript-eslint/no-explicit-any */ import { PROPERTY_METADATA_KEY, PROPERTY_OPTIONS_METADATA_KEY } from './types.js';
 /**
  * Property decorator that marks class properties with metadata.
  * This decorator can be used to identify and track properties within classes.
  *
- * @param options - Optional configuration for the property
+ * @param options - Configuration for the property (type is required)
  *
  * @example
  * class User {
- *   @Property()
+ *   @Property({ type: () => String })
  *   name: string;
  *
- *   @Property({ equals: (a, b) => a.toLowerCase() === b.toLowerCase() })
+ *   @Property({ type: () => String, equals: (a, b) => a.toLowerCase() === b.toLowerCase() })
  *   email: string;
  *
- *   @Property()
+ *   @Property({ type: () => Number })
  *   age: number;
  * }
  */ export function Property(options) {
     return (target, propertyKey)=>{
-        // Only support string property keys
         if (typeof propertyKey !== 'string') {
             return;
         }
-        // Get existing metadata from own property only (not from prototype chain)
         const existingProperties = Reflect.getOwnMetadata(PROPERTY_METADATA_KEY, target) || [];
-        // Add this property if not already tracked
         if (!existingProperties.includes(propertyKey)) {
             existingProperties.push(propertyKey);
         }
-        // Store updated metadata on the target itself
         Reflect.defineMetadata(PROPERTY_METADATA_KEY, existingProperties, target);
-        // Store property options if provided
-        if (options) {
-            const existingOptions = Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, target) || {};
-            existingOptions[propertyKey] = options;
-            Reflect.defineMetadata(PROPERTY_OPTIONS_METADATA_KEY, existingOptions, target);
+        if (options.passthrough === true) {
+            if (options.array === true) {
+                throw new Error(`Property '${propertyKey}' has passthrough: true and array: true. Passthrough cannot be combined with array.`);
+            }
+            if (options.optional === true) {
+                throw new Error(`Property '${propertyKey}' has passthrough: true and optional: true. Passthrough cannot be combined with optional.`);
+            }
+            if (options.sparse === true) {
+                throw new Error(`Property '${propertyKey}' has passthrough: true and sparse: true. Passthrough cannot be combined with sparse.`);
+            }
+            if (options.serialize !== undefined || options.deserialize !== undefined) {
+                throw new Error(`Property '${propertyKey}' has passthrough: true and custom serialize/deserialize functions. Passthrough cannot be combined with serialize or deserialize.`);
+            }
         }
+        if (options.sparse === true && options.array !== true) {
+            throw new Error(`Property '${propertyKey}' has sparse: true but array is not true. The sparse option only applies to arrays.`);
+        }
+        // Validate serialize/deserialize pairing
+        const hasSerialize = options.serialize !== undefined;
+        const hasDeserialize = options.deserialize !== undefined;
+        if (hasSerialize !== hasDeserialize) {
+            throw new Error(`Property '${propertyKey}' must define both serialize and deserialize functions, or neither. Found only ${hasSerialize ? 'serialize' : 'deserialize'}.`);
+        }
+        const existingOptions = Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, target) || {};
+        existingOptions[propertyKey] = options;
+        Reflect.defineMetadata(PROPERTY_OPTIONS_METADATA_KEY, existingOptions, target);
     };
 }
+/**
+ * Helper decorator for string properties
+ * @example
+ * class User {
+ *   @StringProperty()
+ *   name!: string;
+ *
+ *   @StringProperty({ optional: true })
+ *   nickname?: string;
+ * }
+ */ export function StringProperty(options) {
+    return Property({
+        ...options,
+        type: ()=>String
+    });
+}
+/**
+ * Helper decorator for number properties
+ * @example
+ * class User {
+ *   @NumberProperty()
+ *   age!: number;
+ *
+ *   @NumberProperty({ optional: true })
+ *   score?: number;
+ * }
+ */ export function NumberProperty(options) {
+    return Property({
+        ...options,
+        type: ()=>Number
+    });
+}
+/**
+ * Helper decorator for boolean properties
+ * @example
+ * class User {
+ *   @BooleanProperty()
+ *   active!: boolean;
+ *
+ *   @BooleanProperty({ optional: true })
+ *   verified?: boolean;
+ * }
+ */ export function BooleanProperty(options) {
+    return Property({
+        ...options,
+        type: ()=>Boolean
+    });
+}
+/**
+ * Helper decorator for Date properties
+ * @example
+ * class User {
+ *   @DateProperty()
+ *   createdAt!: Date;
+ *
+ *   @DateProperty({ optional: true })
+ *   deletedAt?: Date;
+ * }
+ */ export function DateProperty(options) {
+    return Property({
+        ...options,
+        type: ()=>Date
+    });
+}
+/**
+ * Helper decorator for BigInt properties
+ * @example
+ * class User {
+ *   @BigIntProperty()
+ *   id!: bigint;
+ *
+ *   @BigIntProperty({ optional: true })
+ *   balance?: bigint;
+ * }
+ */ export function BigIntProperty(options) {
+    return Property({
+        ...options,
+        type: ()=>BigInt
+    });
+}
+/**
+ * Helper decorator for entity properties
+ * @example
+ * class User {
+ *   @EntityProperty(() => Address)
+ *   address!: Address;
+ *
+ *   @EntityProperty(() => Profile, { optional: true })
+ *   profile?: Profile;
+ * }
+ */ export function EntityProperty(type, options) {
+    return Property({
+        ...options,
+        type
+    });
+}
+/**
+ * Helper decorator for array properties
+ * @example
+ * class User {
+ *   @ArrayProperty(() => String)
+ *   tags!: string[];
+ *
+ *   @ArrayProperty(() => Phone)
+ *   phones!: Phone[];
+ *
+ *   @ArrayProperty(() => Number, { optional: true })
+ *   scores?: number[];
+ *
+ *   @ArrayProperty(() => String, { sparse: true })
+ *   sparseList!: (string | null)[];
+ * }
+ */ export function ArrayProperty(type, options) {
+    return Property({
+        ...options,
+        type,
+        array: true
+    });
+}
+/**
+ * Helper decorator for passthrough properties that bypass type validation.
+ * Use this for generic types like Record<string, unknown>, any, or custom objects.
+ * @example
+ * class Config {
+ *   @PassthroughProperty()
+ *   metadata!: Record<string, unknown>;
+ *
+ *   @PassthroughProperty()
+ *   customData!: any;
+ * }
+ */ export function PassthroughProperty() {
+    // Use a dummy type since type is mandatory but not used with passthrough
+    return Property({
+        type: ()=>Object,
+        passthrough: true
+    });
+}
 
 //# sourceMappingURL=property.js.map

package/dist/lib/property.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/property.ts"],"sourcesContent":["import {\n  PROPERTY_METADATA_KEY,\n  PROPERTY_OPTIONS_METADATA_KEY,\n  PropertyOptions,\n} from './types.js';\n\n/**\n * Property decorator that marks class properties with metadata.\n * This decorator can be used to identify and track properties within classes.\n *\n * @param options - Optional configuration for the property\n *\n * @example\n * class User {\n *   @Property()\n *   name: string;\n *\n *   @Property({ equals: (a, b) => a.toLowerCase() === b.toLowerCase() })\n *   email: string;\n *\n *   @Property()\n *   age: number;\n * }\n */\nexport function Property<T = any>(\n  options?: PropertyOptions<T>,\n): PropertyDecorator {\n  return (target: object, propertyKey: string | symbol): void => {\n    // Only support string property keys\n    if (typeof propertyKey !== 'string') {\n      return;\n    }\n\n    // Get existing metadata from own property only (not from prototype chain)\n    const existingProperties: string[] =\n      Reflect.getOwnMetadata(PROPERTY_METADATA_KEY, target) || [];\n\n    // Add this property if not already tracked\n    if (!existingProperties.includes(propertyKey)) {\n      existingProperties.push(propertyKey);\n    }\n\n    // Store updated metadata on the target itself\n    Reflect.defineMetadata(PROPERTY_METADATA_KEY, existingProperties, target);\n\n    // Store property options if provided\n    if (options) {\n      const existingOptions: Record<string, PropertyOptions> =\n        Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, target) || {};\n\n      existingOptions[propertyKey] = options;\n\n      Reflect.defineMetadata(\n        PROPERTY_OPTIONS_METADATA_KEY,\n        existingOptions,\n        target,\n      );\n    }\n  };\n}\n"],"names":["PROPERTY_METADATA_KEY","PROPERTY_OPTIONS_METADATA_KEY","Property","options","target","propertyKey","existingProperties","Reflect","getOwnMetadata","includes","push","defineMetadata","existingOptions"],"mappings":"AAAA,SACEA,qBAAqB,EACrBC,6BAA6B,QAExB,aAAa;AAEpB;;;;;;;;;;;;;;;;;CAiBC,GACD,OAAO,SAASC,SACdC,OAA4B;IAE5B,OAAO,CAACC,QAAgBC;QACtB,oCAAoC;QACpC,IAAI,OAAOA,gBAAgB,UAAU;YACnC;QACF;QAEA,0EAA0E;QAC1E,MAAMC,qBACJC,QAAQC,cAAc,CAACR,uBAAuBI,WAAW,EAAE;QAE7D,2CAA2C;QAC3C,IAAI,CAACE,mBAAmBG,QAAQ,CAACJ,cAAc;YAC7CC,mBAAmBI,IAAI,CAACL;QAC1B;QAEA,8CAA8C;QAC9CE,QAAQI,cAAc,CAACX,uBAAuBM,oBAAoBF;QAElE,qCAAqC;QACrC,IAAID,SAAS;YACX,MAAMS,kBACJL,QAAQC,cAAc,CAACP,+BAA+BG,WAAW,CAAC;YAEpEQ,eAAe,CAACP,YAAY,GAAGF;YAE/BI,QAAQI,cAAc,CACpBV,+BACAW,iBACAR;QAEJ;IACF;AACF"}
+{"version":3,"sources":["../../src/lib/property.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-wrapper-object-types */\n/* eslint-disable @typescript-eslint/no-explicit-any */\nimport {\n  AnyCtor,\n  type CtorLike,\n  PROPERTY_METADATA_KEY,\n  PROPERTY_OPTIONS_METADATA_KEY,\n  PropertyOptions,\n} from './types.js';\n\n/**\n * Property decorator that marks class properties with metadata.\n * This decorator can be used to identify and track properties within classes.\n *\n * @param options - Configuration for the property (type is required)\n *\n * @example\n * class User {\n *   @Property({ type: () => String })\n *   name: string;\n *\n *   @Property({ type: () => String, equals: (a, b) => a.toLowerCase() === b.toLowerCase() })\n *   email: string;\n *\n *   @Property({ type: () => Number })\n *   age: number;\n * }\n */\nexport function Property<T, C extends CtorLike<T>>(\n  options: PropertyOptions<T, C>,\n): PropertyDecorator {\n  return (target: object, propertyKey: string | symbol): void => {\n    if (typeof propertyKey !== 'string') {\n      return;\n    }\n\n    const existingProperties: string[] =\n      Reflect.getOwnMetadata(PROPERTY_METADATA_KEY, target) || [];\n\n    if (!existingProperties.includes(propertyKey)) {\n      existingProperties.push(propertyKey);\n    }\n\n    Reflect.defineMetadata(PROPERTY_METADATA_KEY, existingProperties, target);\n\n    if (options.passthrough === true) {\n      if (options.array === true) {\n        throw new Error(\n          `Property '${propertyKey}' has passthrough: true and array: true. Passthrough cannot be combined with array.`,\n        );\n      }\n      if (options.optional === true) {\n        throw new Error(\n          `Property '${propertyKey}' has passthrough: true and optional: true. Passthrough cannot be combined with optional.`,\n        );\n      }\n      if (options.sparse === true) {\n        throw new Error(\n          `Property '${propertyKey}' has passthrough: true and sparse: true. Passthrough cannot be combined with sparse.`,\n        );\n      }\n      if (\n        options.serialize !== undefined ||\n        options.deserialize !== undefined\n      ) {\n        throw new Error(\n          `Property '${propertyKey}' has passthrough: true and custom serialize/deserialize functions. Passthrough cannot be combined with serialize or deserialize.`,\n        );\n      }\n    }\n\n    if (options.sparse === true && options.array !== true) {\n      throw new Error(\n        `Property '${propertyKey}' has sparse: true but array is not true. The sparse option only applies to arrays.`,\n      );\n    }\n\n    // Validate serialize/deserialize pairing\n    const hasSerialize = options.serialize !== undefined;\n    const hasDeserialize = options.deserialize !== undefined;\n    if (hasSerialize !== hasDeserialize) {\n      throw new Error(\n        `Property '${propertyKey}' must define both serialize and deserialize functions, or neither. Found only ${hasSerialize ? 'serialize' : 'deserialize'}.`,\n      );\n    }\n\n    const existingOptions: Record<\n      string,\n      PropertyOptions<any, any>\n    > = Reflect.getOwnMetadata(PROPERTY_OPTIONS_METADATA_KEY, target) || {};\n\n    existingOptions[propertyKey] = options;\n\n    Reflect.defineMetadata(\n      PROPERTY_OPTIONS_METADATA_KEY,\n      existingOptions,\n      target,\n    );\n  };\n}\n\n/**\n * Helper decorator for string properties\n * @example\n * class User {\n *   @StringProperty()\n *   name!: string;\n *\n *   @StringProperty({ optional: true })\n *   nickname?: string;\n * }\n */\nexport function StringProperty(\n  options?: Omit<PropertyOptions<string, StringConstructor>, 'type'>,\n): PropertyDecorator {\n  return Property({ ...options, type: () => String });\n}\n\n/**\n * Helper decorator for number properties\n * @example\n * class User {\n *   @NumberProperty()\n *   age!: number;\n *\n *   @NumberProperty({ optional: true })\n *   score?: number;\n * }\n */\nexport function NumberProperty(\n  options?: Omit<PropertyOptions<number, NumberConstructor>, 'type'>,\n): PropertyDecorator {\n  return Property({ ...options, type: () => Number });\n}\n\n/**\n * Helper decorator for boolean properties\n * @example\n * class User {\n *   @BooleanProperty()\n *   active!: boolean;\n *\n *   @BooleanProperty({ optional: true })\n *   verified?: boolean;\n * }\n */\nexport function BooleanProperty(\n  options?: Omit<PropertyOptions<boolean, BooleanConstructor>, 'type'>,\n): PropertyDecorator {\n  return Property({ ...options, type: () => Boolean });\n}\n\n/**\n * Helper decorator for Date properties\n * @example\n * class User {\n *   @DateProperty()\n *   createdAt!: Date;\n *\n *   @DateProperty({ optional: true })\n *   deletedAt?: Date;\n * }\n */\nexport function DateProperty(\n  options?: Omit<PropertyOptions<Date, DateConstructor>, 'type'>,\n): PropertyDecorator {\n  return Property({ ...options, type: () => Date });\n}\n\n/**\n * Helper decorator for BigInt properties\n * @example\n * class User {\n *   @BigIntProperty()\n *   id!: bigint;\n *\n *   @BigIntProperty({ optional: true })\n *   balance?: bigint;\n * }\n */\nexport function BigIntProperty(\n  options?: Omit<PropertyOptions<bigint, BigIntConstructor>, 'type'>,\n): PropertyDecorator {\n  return Property({ ...options, type: () => BigInt });\n}\n\n/**\n * Helper decorator for entity properties\n * @example\n * class User {\n *   @EntityProperty(() => Address)\n *   address!: Address;\n *\n *   @EntityProperty(() => Profile, { optional: true })\n *   profile?: Profile;\n * }\n */\nexport function EntityProperty<T, C extends AnyCtor<T>>(\n  type: () => C,\n  options?: Omit<PropertyOptions<T, C>, 'type'>,\n): PropertyDecorator {\n  return Property<T, C>({ ...options, type });\n}\n\n/**\n * Helper decorator for array properties\n * @example\n * class User {\n *   @ArrayProperty(() => String)\n *   tags!: string[];\n *\n *   @ArrayProperty(() => Phone)\n *   phones!: Phone[];\n *\n *   @ArrayProperty(() => Number, { optional: true })\n *   scores?: number[];\n *\n *   @ArrayProperty(() => String, { sparse: true })\n *   sparseList!: (string | null)[];\n * }\n */\nexport function ArrayProperty<T, C extends CtorLike<T>>(\n  type: () => C,\n  options?: Omit<PropertyOptions<T, C>, 'type' | 'array'>,\n): PropertyDecorator {\n  return Property({ ...options, type, array: true });\n}\n\n/**\n * Helper decorator for passthrough properties that bypass type validation.\n * Use this for generic types like Record<string, unknown>, any, or custom objects.\n * @example\n * class Config {\n *   @PassthroughProperty()\n *   metadata!: Record<string, unknown>;\n *\n *   @PassthroughProperty()\n *   customData!: any;\n * }\n */\nexport function PassthroughProperty(): PropertyDecorator {\n  // Use a dummy type since type is mandatory but not used with passthrough\n  return Property({ type: () => Object, passthrough: true });\n}\n"],"names":["PROPERTY_METADATA_KEY","PROPERTY_OPTIONS_METADATA_KEY","Property","options","target","propertyKey","existingProperties","Reflect","getOwnMetadata","includes","push","defineMetadata","passthrough","array","Error","optional","sparse","serialize","undefined","deserialize","hasSerialize","hasDeserialize","existingOptions","StringProperty","type","String","NumberProperty","Number","BooleanProperty","Boolean","DateProperty","Date","BigIntProperty","BigInt","EntityProperty","ArrayProperty","PassthroughProperty","Object"],"mappings":"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"}

package/dist/lib/types.d.ts

@@ -10,16 +10,94 @@ export declare const PROPERTY_OPTIONS_METADATA_KEY: unique symbol;
  * Metadata key used to store entity information
  */
 export declare const ENTITY_METADATA_KEY: unique symbol;
+export type AnyCtor<T = any> = abstract new (...args: any[]) => T;
+export type BuiltinCtors = StringConstructor | NumberConstructor | BooleanConstructor | BigIntConstructor | SymbolConstructor | DateConstructor;
+export type CtorLike<T> = AnyCtor<T> | BuiltinCtors;
+export type InstanceOfCtorLike<C> = C extends StringConstructor ? string : C extends NumberConstructor ? number : C extends BooleanConstructor ? boolean : C extends BigIntConstructor ? bigint : C extends SymbolConstructor ? symbol : C extends DateConstructor ? Date : C extends AnyCtor<infer T> ? T : never;
 /**
  * Options for the Property decorator
  */
-export interface PropertyOptions<T = any> {
+export interface PropertyOptions<T = any, C extends CtorLike<T> = AnyCtor<T> | BuiltinCtors> {
     /**
      * Custom equality comparison function for this property
      * @param a - First value to compare
      * @param b - Second value to compare
      * @returns true if values are equal, false otherwise
      */
-    equals?: (a: T, b: T) => boolean;
+    equals?: (a: InstanceOfCtorLike<C>, b: InstanceOfCtorLike<C>) => boolean;
+    /**
+     * Type constructor for this property. Required for EntityUtils.parse() support.
+     * Use a function that returns the type constructor to support forward references.
+     * @example
+     * @Property({ type: () => String })
+     * name!: string;
+     *
+     * @Property({ type: () => Address })
+     * address!: Address;
+     */
+    type: () => C;
+    /**
+     * Whether this property is an array. Defaults to false.
+     * When true, the deserializer will map over array elements.
+     * @example
+     * @Property({ type: () => String, array: true })
+     * tags!: string[];
+     */
+    array?: boolean;
+    /**
+     * Whether this property is optional. Defaults to false.
+     * When true, the property can be undefined or null.
+     * When false, the property must be present and not null/undefined.
+     * @example
+     * @Property({ type: () => String, optional: true })
+     * nickname?: string;
+     */
+    optional?: boolean;
+    /**
+     * Whether the array can contain null/undefined elements. Defaults to false.
+     * Only applicable when array is true.
+     * When false (default), null/undefined elements will cause an error.
+     * When true, null/undefined elements are allowed in the array.
+     * @example
+     * @Property({ type: () => String, array: true, sparse: true })
+     * tags!: (string | null)[];
+     */
+    sparse?: boolean;
+    /**
+     * Whether to bypass type validation and pass values through as-is.
+     * Use this for generic types like Record<string, unknown> or any.
+     * When true, no type checking or transformation is performed.
+     * Also bypasses any custom serialize/deserialize callbacks.
+     * @example
+     * @Property({ passthrough: true })
+     * metadata!: Record<string, unknown>;
+     */
+    passthrough?: boolean;
+    /**
+     * Custom serialization function to convert the property value to JSON-compatible format.
+     * Must be paired with deserialize - both must be defined together or both omitted.
+     * Not used when passthrough is true.
+     * @example
+     * @Property({
+     *   type: () => MyClass,
+     *   serialize: (value) => ({ data: value.toData() }),
+     *   deserialize: (json) => MyClass.fromData(json.data)
+     * })
+     * myProperty!: MyClass;
+     */
+    serialize?: (value: InstanceOfCtorLike<C>) => unknown;
+    /**
+     * Custom deserialization function to convert JSON data back to the property type.
+     * Must be paired with serialize - both must be defined together or both omitted.
+     * Not used when passthrough is true.
+     * @example
+     * @Property({
+     *   type: () => MyClass,
+     *   serialize: (value) => ({ data: value.toData() }),
+     *   deserialize: (json) => MyClass.fromData(json.data)
+     * })
+     * myProperty!: MyClass;
+     */
+    deserialize?: (serialized: unknown) => InstanceOfCtorLike<C>;
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAA8B,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,6BAA6B,eAEzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAA4B,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,GAAG;IACtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC;CAClC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/lib/types.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,qBAAqB,eAA8B,CAAC;AAEjE;;GAEG;AACH,eAAO,MAAM,6BAA6B,eAEzC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,mBAAmB,eAA4B,CAAC;AAE7D,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,GAAG,IAAI,QAAQ,MAAM,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAElE,MAAM,MAAM,YAAY,GACpB,iBAAiB,GACjB,iBAAiB,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,iBAAiB,GACjB,eAAe,CAAC;AAEpB,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY,CAAC;AAEpD,MAAM,MAAM,kBAAkB,CAAC,CAAC,IAAI,CAAC,SAAS,iBAAiB,GAC3D,MAAM,GACN,CAAC,SAAS,iBAAiB,GACzB,MAAM,GACN,CAAC,SAAS,kBAAkB,GAC1B,OAAO,GACP,CAAC,SAAS,iBAAiB,GACzB,MAAM,GACN,CAAC,SAAS,iBAAiB,GACzB,MAAM,GACN,CAAC,SAAS,eAAe,GACvB,IAAI,GACJ,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GACxB,CAAC,GACD,KAAK,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,eAAe,CAC9B,CAAC,GAAG,GAAG,EACP,CAAC,SAAS,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,YAAY;IAEjD;;;;;OAKG;IACH,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAEzE;;;;;;;;;OASG;IACH,IAAI,EAAE,MAAM,CAAC,CAAC;IAEd;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAEhB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;;;;;;OAQG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,kBAAkB,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC;IAEtD;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE,OAAO,KAAK,kBAAkB,CAAC,CAAC,CAAC,CAAC;CAC9D"}

package/dist/lib/types.js

@@ -1,4 +1,4 @@
-/**
+/* eslint-disable @typescript-eslint/no-explicit-any */ /* eslint-disable @typescript-eslint/no-wrapper-object-types */ /**
  * Metadata key used to store property information
  */ export const PROPERTY_METADATA_KEY = Symbol('property:metadata');
 /**

package/dist/lib/types.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/lib/types.ts"],"sourcesContent":["/**\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 * Options for the Property decorator\n */\nexport interface PropertyOptions<T = any> {\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: T, b: T) => boolean;\n}\n"],"names":["PROPERTY_METADATA_KEY","Symbol","PROPERTY_OPTIONS_METADATA_KEY","ENTITY_METADATA_KEY"],"mappings":"AAAA;;CAEC,GACD,OAAO,MAAMA,wBAAwBC,OAAO,qBAAqB;AAEjE;;CAEC,GACD,OAAO,MAAMC,gCAAgCD,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAME,sBAAsBF,OAAO,mBAAmB"}
+{"version":3,"sources":["../../src/lib/types.ts"],"sourcesContent":["/* eslint-disable @typescript-eslint/no-explicit-any */\n/* eslint-disable @typescript-eslint/no-wrapper-object-types */\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\nexport type AnyCtor<T = any> = abstract new (...args: any[]) => T;\n\nexport type BuiltinCtors =\n  | StringConstructor\n  | NumberConstructor\n  | BooleanConstructor\n  | BigIntConstructor\n  | SymbolConstructor\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   * @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   * 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"],"names":["PROPERTY_METADATA_KEY","Symbol","PROPERTY_OPTIONS_METADATA_KEY","ENTITY_METADATA_KEY"],"mappings":"AAAA,qDAAqD,GACrD,6DAA6D,GAC7D;;CAEC,GACD,OAAO,MAAMA,wBAAwBC,OAAO,qBAAqB;AAEjE;;CAEC,GACD,OAAO,MAAMC,gCAAgCD,OAC3C,6BACA;AAEF;;CAEC,GACD,OAAO,MAAME,sBAAsBF,OAAO,mBAAmB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rtpaulino/entity",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -47,7 +47,7 @@
     }
   },
   "dependencies": {
-    "@rtpaulino/core": "^0.11.0",
+    "@rtpaulino/core": "^0.13.0",
     "@swc/helpers": "~0.5.18",
     "lodash-es": "^4.17.22"
   },