@cheetah.js/orm 0.1.106 → 0.1.107

package/README.md

@@ -123,7 +123,7 @@ export class User {
 }
 ```
 
-For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
+For define a index for a multiple properties, add the @Index decorator. You can use it on a property or on the class. It accepts either an array of property names (legacy) or an object with a properties field (recommended):
 
 ```javascript
 @Entity()
@@ -134,29 +134,29 @@ export class User {
     @Property()
     name: string;
 
-    // Property-level (compound index)
-    @Index({ properties: ['name', 'email'] })
-    @Property()
-    email: string;
-}
-
-// Or, at the class level
-
-@Entity()
-@Index<{ User }>({ properties: ['name', 'email'] })
-export class User {
-  @PrimaryKey()
-  id: number;
-
-  @Property()
-  name: string;
-
-  @Property()
-  email: string;
-}
-
-// Backward compatible usage (array):
-// @Index(['name', 'email'])
+    // Property-level (compound index)
+    @Index({ properties: ['name', 'email'] })
+    @Property()
+    email: string;
+}
+
+// Or, at the class level
+
+@Entity()
+@Index<{ User }>({ properties: ['name', 'email'] })
+export class User {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  name: string;
+
+  @Property()
+  email: string;
+}
+
+// Backward compatible usage (array):
+// @Index(['name', 'email'])
 ```
 
 #### Property options
@@ -170,6 +170,56 @@ export class User {
 | onUpdate | string | Define the action to be taken for this property when updating the entity in the database   |
 | onInsert | string | Defines the action to be taken for this property when inserting the entity in the database |
 
+#### Computed Properties
+The `@Computed` decorator allows you to define properties that are included in serialization but NOT persisted to the database. This is useful for derived values, formatted data, or any computation based on existing properties.
+
+Computed properties are evaluated when the entity is serialized (e.g., `JSON.stringify()`) and are perfect for transforming or combining existing data.
+
+##### Example:
+```javascript
+import { Entity, PrimaryKey, Property, Computed } from '@cheetah.js/orm';
+
+@Entity()
+export class Article {
+  @PrimaryKey()
+  id: number;
+
+  @Property()
+  title: string;
+
+  @Property()
+  body: string;
+
+  @Computed()
+  get excerpt() {
+    return this.body?.substring(0, 50) || '';
+  }
+
+  @Computed()
+  get titleUppercase() {
+    return this.title?.toUpperCase() || '';
+  }
+}
+```
+
+When you serialize an article:
+```javascript
+const article = await Article.create({
+  title: 'My Article',
+  body: 'This is the full body text of the article...'
+});
+
+console.log(JSON.stringify(article));
+// Output: {"id":1,"title":"My Article","body":"This is the full body text of the article...","excerpt":"This is the full body text of the article...","titleUppercase":"MY ARTICLE"}
+```
+
+**Important Notes:**
+- Computed properties are **NOT** stored in the database
+- They are evaluated during serialization (toJSON)
+- Best used with getter functions
+- Can access other properties and even other computed properties
+- Can return any JSON-serializable type (string, number, object, array, etc.)
+
 ### [Hooks](#hooks)
 Cheetah ORM supports hooks for entities. The available hooks are: BeforeCreate, AfterCreate, BeforeUpdate, AfterUpdate, BeforeDelete, AfterDelete.
 Hooks is only for modify the entity, not for create, update or delete another entities statements in database.
@@ -317,21 +367,21 @@ const user = await User.findOne({
 | $ne | Not Equal | Matches all values that are not equal to a specified value. |
 | $nin | Not In | Matches none of the values specified in an array. |
 | $and | And | Joins query clauses with a logical AND returns all documents that match the conditions of both clauses. |
- | $or | Or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause. |
-| $not | Not | Inverts the effect of a query expression and returns documents that do not match the query expression. |
-
-#### Filter by Date columns
-You can filter using JavaScript `Date` instances and the ORM translates them into precise SQL comparisons:
-
-```typescript
-const reinforcement = await User.findOne({
-  updatedAt: new Date('2024-06-01T00:00:00.000Z'),
-});
-```
-
-### [Migrations](#migrations)
-Cheetah ORM is capable of creating and running migrations.
-To do this, you need to install our cli package:
+ | $or | Or | Joins query clauses with a logical OR returns all documents that match the conditions of either clause. |
+| $not | Not | Inverts the effect of a query expression and returns documents that do not match the query expression. |
+
+#### Filter by Date columns
+You can filter using JavaScript `Date` instances and the ORM translates them into precise SQL comparisons:
+
+```typescript
+const reinforcement = await User.findOne({
+  updatedAt: new Date('2024-06-01T00:00:00.000Z'),
+});
+```
+
+### [Migrations](#migrations)
+Cheetah ORM is capable of creating and running migrations.
+To do this, you need to install our cli package:
 
 ```bash
 bun install @cheetah.js/cli

package/dist/constants.d.ts

@@ -3,3 +3,4 @@ export declare const PROPERTIES = "cheetah:properties";
 export declare const PROPERTIES_METADATA = "cheetah:properties:metadata";
 export declare const PROPERTIES_RELATIONS = "cheetah:properties:relations";
 export declare const EVENTS_METADATA = "cheetah:events:metadata";
+export declare const COMPUTED_PROPERTIES = "cheetah:computed:properties";

package/dist/constants.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EVENTS_METADATA = exports.PROPERTIES_RELATIONS = exports.PROPERTIES_METADATA = exports.PROPERTIES = exports.ENTITIES = void 0;
+exports.COMPUTED_PROPERTIES = exports.EVENTS_METADATA = exports.PROPERTIES_RELATIONS = exports.PROPERTIES_METADATA = exports.PROPERTIES = exports.ENTITIES = void 0;
 exports.ENTITIES = 'cheetah:entities';
 exports.PROPERTIES = 'cheetah:properties';
 exports.PROPERTIES_METADATA = 'cheetah:properties:metadata';
 exports.PROPERTIES_RELATIONS = 'cheetah:properties:relations';
 exports.EVENTS_METADATA = 'cheetah:events:metadata';
+exports.COMPUTED_PROPERTIES = 'cheetah:computed:properties';

package/dist/decorators/computed.decorator.d.ts

@@ -0,0 +1 @@
+export declare function Computed(): PropertyDecorator;

package/dist/decorators/computed.decorator.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Computed = Computed;
+const core_1 = require("@cheetah.js/core");
+const constants_1 = require("../constants");
+function Computed() {
+    return (target, propertyKey) => {
+        const computedProperties = core_1.Metadata.get(constants_1.COMPUTED_PROPERTIES, target.constructor) || [];
+        computedProperties.push(propertyKey);
+        core_1.Metadata.set(constants_1.COMPUTED_PROPERTIES, computedProperties, target.constructor);
+    };
+}

package/dist/domain/base-entity.d.ts

@@ -47,4 +47,11 @@ export declare abstract class BaseEntity {
      */
     isPersisted(): boolean;
     toJSON(): Record<string, any>;
+    private serializeWithEntity;
+    private serializeWithMetadata;
+    private shouldSkipProperty;
+    private shouldSkipPropertyBasic;
+    private isInternalProperty;
+    private getHiddenPropertiesFromMetadata;
+    private addComputedProperties;
 }

package/dist/domain/base-entity.js

@@ -3,6 +3,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.BaseEntity = void 0;
 const SqlBuilder_1 = require("../SqlBuilder");
 const entities_1 = require("./entities");
+const core_1 = require("@cheetah.js/core");
+const constants_1 = require("../constants");
 class BaseEntity {
     constructor() {
         this._oldValues = {};
@@ -121,24 +123,71 @@ class BaseEntity {
         return this.$_isPersisted;
     }
     toJSON() {
-        let data = {};
-        let storage = entities_1.EntityStorage.getInstance();
-        let entity = storage.get(this.constructor);
-        let allProperties = new Map(Object.entries(entity.properties).map(([key, value]) => [key, value]));
+        const storage = entities_1.EntityStorage.getInstance();
+        const entity = storage.get(this.constructor);
+        const data = entity
+            ? this.serializeWithEntity(entity)
+            : this.serializeWithMetadata();
+        this.addComputedProperties(data);
+        return data;
+    }
+    serializeWithEntity(entity) {
+        const data = {};
+        const allProperties = new Set(Object.keys(entity.properties));
+        const hidePropertiesSet = new Set(entity.hideProperties);
         for (const key in this) {
-            // if starts with $ or _, ignore
-            if (key.startsWith('$') || key.startsWith('_')) {
-                continue;
-            }
-            if (!allProperties.has(key)) {
+            if (this.shouldSkipProperty(key, allProperties, hidePropertiesSet)) {
                 continue;
             }
-            if (entity.hideProperties.includes(key)) {
+            data[key] = this[key];
+        }
+        return data;
+    }
+    serializeWithMetadata() {
+        const data = {};
+        const hideProperties = this.getHiddenPropertiesFromMetadata();
+        const hidePropertiesSet = new Set(hideProperties);
+        for (const key in this) {
+            if (this.shouldSkipPropertyBasic(key, hidePropertiesSet)) {
                 continue;
             }
             data[key] = this[key];
         }
         return data;
     }
+    shouldSkipProperty(key, allProperties, hideProperties) {
+        if (this.isInternalProperty(key)) {
+            return true;
+        }
+        if (!allProperties.has(key)) {
+            return true;
+        }
+        return hideProperties.has(key);
+    }
+    shouldSkipPropertyBasic(key, hideProperties) {
+        if (this.isInternalProperty(key)) {
+            return true;
+        }
+        return hideProperties.has(key);
+    }
+    isInternalProperty(key) {
+        return key.startsWith('$') || key.startsWith('_');
+    }
+    getHiddenPropertiesFromMetadata() {
+        const properties = core_1.Metadata.get(constants_1.PROPERTIES_METADATA, this.constructor) || {};
+        const hideProperties = [];
+        for (const [key, prop] of Object.entries(properties)) {
+            if (prop.options?.hidden) {
+                hideProperties.push(key);
+            }
+        }
+        return hideProperties;
+    }
+    addComputedProperties(data) {
+        const computedProperties = core_1.Metadata.get(constants_1.COMPUTED_PROPERTIES, this.constructor) || [];
+        for (const key of computedProperties) {
+            data[key] = this[key];
+        }
+    }
 }
 exports.BaseEntity = BaseEntity;

package/dist/index.d.ts

@@ -5,6 +5,7 @@ export * from './decorators/one-many.decorator';
 export * from './decorators/index.decorator';
 export * from './decorators/event-hook.decorator';
 export * from './decorators/enum.decorator';
+export * from './decorators/computed.decorator';
 export * from './orm';
 export * from './orm.service';
 export * from './domain/base-entity';

package/dist/index.js

@@ -22,6 +22,7 @@ __exportStar(require("./decorators/one-many.decorator"), exports);
 __exportStar(require("./decorators/index.decorator"), exports);
 __exportStar(require("./decorators/event-hook.decorator"), exports);
 __exportStar(require("./decorators/enum.decorator"), exports);
+__exportStar(require("./decorators/computed.decorator"), exports);
 __exportStar(require("./orm"), exports);
 __exportStar(require("./orm.service"), exports);
 __exportStar(require("./domain/base-entity"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cheetah.js/orm",
-  "version": "0.1.106",
+  "version": "0.1.107",
   "description": "A simple ORM for Cheetah.js",
   "type": "commonjs",
   "main": "dist/index.js",
@@ -55,5 +55,5 @@
     "bun",
     "value-object"
   ],
-  "gitHead": "90721637d6b394e2bbf17278296122111358b881"
+  "gitHead": "0c79e3c070683f0a432056d7e57d6d6a6a53b190"
 }