feat(orm): add support for runtime virtual fields

packages/language/res/stdlib.zmodel

@@ -643,6 +643,15 @@ attribute @json() @@@targetField([TypeDefField])
  */
 attribute @computed()
 
+/**
+ * Marks a field to be virtual (computed at runtime in JavaScript).
+ *
+ * @param dependencies: A list of fields that this virtual field depends on. When the virtual field
+ * is selected, these fields will be automatically included in the database query even if not
+ * explicitly selected by the user, and will be stripped from the result after computation.
+ */
+attribute @virtual(dependencies: FieldReference[]?)
+
 /**
  * Gets the current login user.
  */

packages/language/src/utils.ts

@@ -154,6 +154,13 @@ export function isComputedField(field: DataField) {
     return hasAttribute(field, '@computed');
 }
 
+/**
+ * Returns if the given field is a virtual field.
+ */
+export function isVirtualField(field: DataField) {
+    return hasAttribute(field, '@virtual');
+}
+
 export function isDelegateModel(node: AstNode) {
     return isDataModel(node) && hasAttribute(node, '@@delegate');
 }

packages/orm/src/client/client-impl.ts

@@ -456,7 +456,7 @@ function createModelCrudHandler(
                 }
                 let result: unknown;
                 if (r && postProcess) {
-                    result = resultProcessor.processResult(r, model, args);
+                    result = await resultProcessor.processResult(r, model, args, txClient ?? client);
                 } else {
                     result = r ?? null;
                 }

packages/orm/src/client/crud-types.ts

@@ -8,6 +8,7 @@ import type {
     FieldIsDelegateDiscriminator,
     FieldIsDelegateRelation,
     FieldIsRelation,
+    FieldIsVirtual,
     FieldType,
     ForeignKeyFields,
     GetEnum,
@@ -23,6 +24,8 @@ import type {
     GetTypeDefs,
     ModelFieldIsOptional,
     NonRelationFields,
+    NonVirtualFields,
+    NonVirtualNonRelationFields,
     ProcedureDef,
     RelationFields,
     RelationFieldType,
@@ -281,7 +284,8 @@ export type WhereInput<
     ScalarOnly extends boolean = false,
     WithAggregations extends boolean = false,
 > = {
-    [Key in GetModelFields<Schema, Model> as ScalarOnly extends true
+    // Use NonVirtualFields to exclude virtual fields - they are computed at runtime and cannot be filtered in the database
+    [Key in NonVirtualFields<Schema, Model> as ScalarOnly extends true
         ? Key extends RelationFields<Schema, Model>
             ? never
             : Key
@@ -755,7 +759,8 @@ export type OrderBy<
     WithRelation extends boolean,
     WithAggregation extends boolean,
 > = {
-    [Key in NonRelationFields<Schema, Model>]?: ModelFieldIsOptional<Schema, Model, Key> extends true
+    // Use NonVirtualNonRelationFields to exclude virtual fields - they are computed at runtime and cannot be sorted in the database
+    [Key in NonVirtualNonRelationFields<Schema, Model>]?: ModelFieldIsOptional<Schema, Model, Key> extends true
         ?
               | SortOrder
               | {
@@ -968,7 +973,7 @@ type RelationFilter<
 
 //#region Field utils
 
-type MapModelFieldType<
+export type MapModelFieldType<
     Schema extends SchemaDef,
     Model extends GetModels<Schema>,
     Field extends GetModelFields<Schema, Model>,
@@ -1354,7 +1359,7 @@ type UpdateScalarInput<
     Without extends string = never,
 > = Omit<
     {
-        [Key in NonRelationFields<Schema, Model> as FieldIsDelegateDiscriminator<Schema, Model, Key> extends true
+        [Key in NonVirtualNonRelationFields<Schema, Model> as FieldIsDelegateDiscriminator<Schema, Model, Key> extends true
             ? // discriminator fields cannot be assigned
               never
             : Key]?: ScalarUpdatePayload<Schema, Model, Key>;
@@ -1365,7 +1370,7 @@ type UpdateScalarInput<
 type ScalarUpdatePayload<
     Schema extends SchemaDef,
     Model extends GetModels<Schema>,
-    Field extends NonRelationFields<Schema, Model>,
+    Field extends NonVirtualNonRelationFields<Schema, Model>,
 > =
     | ScalarFieldMutationPayload<Schema, Model, Field>
     | (Field extends NumericFields<Schema, Model>
@@ -1587,7 +1592,7 @@ export type CountArgs<Schema extends SchemaDef, Model extends GetModels<Schema>>
 };
 
 type CountAggregateInput<Schema extends SchemaDef, Model extends GetModels<Schema>> = {
-    [Key in NonRelationFields<Schema, Model>]?: true;
+    [Key in NonVirtualNonRelationFields<Schema, Model>]?: true;
 } & { _all?: true };
 
 export type CountResult<Schema extends SchemaDef, _Model extends GetModels<Schema>, Args> = Args extends {
@@ -1661,7 +1666,9 @@ type NumericFields<Schema extends SchemaDef, Model extends GetModels<Schema>> =
         | 'Decimal'
         ? FieldIsArray<Schema, Model, Key> extends true
             ? never
-            : Key
+            : FieldIsVirtual<Schema, Model, Key> extends true
+              ? never
+              : Key
         : never]: GetModelField<Schema, Model, Key>;
 };
 
@@ -1674,7 +1681,9 @@ type MinMaxInput<Schema extends SchemaDef, Model extends GetModels<Schema>, Valu
         ? never
         : FieldIsRelation<Schema, Model, Key> extends true
           ? never
-          : Key]?: ValueType;
+          : FieldIsVirtual<Schema, Model, Key> extends true
+            ? never
+            : Key]?: ValueType;
 };
 
 export type AggregateResult<Schema extends SchemaDef, _Model extends GetModels<Schema>, Args> = (Args extends {
@@ -1751,7 +1760,7 @@ export type GroupByArgs<Schema extends SchemaDef, Model extends GetModels<Schema
     /**
      * Fields to group by
      */
-    by: NonRelationFields<Schema, Model> | NonEmptyArray<NonRelationFields<Schema, Model>>;
+    by: NonVirtualNonRelationFields<Schema, Model> | NonEmptyArray<NonVirtualNonRelationFields<Schema, Model>>;
 
     /**
      * Filter conditions for the grouped records

packages/orm/src/client/crud/dialects/base-dialect.ts

@@ -1126,11 +1126,36 @@ export abstract class BaseCrudDialect<Schema extends SchemaDef> {
         const modelDef = requireModel(this.schema, model);
         let result = query;
 
+        // Collect dependency fields needed by non-omitted virtual fields
+        // so they're fetched even if the user omits them
+        const depsNeeded = new Set<string>();
+        if (omit && modelDef.virtualFields) {
+            for (const vFieldName of Object.keys(modelDef.virtualFields)) {
+                if (!this.shouldOmitField(omit, model, vFieldName)) {
+                    const vFieldDef = modelDef.fields[vFieldName];
+                    const deps =
+                        typeof vFieldDef?.virtual === 'object'
+                            ? vFieldDef.virtual.dependencies
+                            : undefined;
+                    if (deps) {
+                        for (const dep of deps) {
+                            depsNeeded.add(dep);
+                        }
+                    }
+                }
+            }
+        }
+
         for (const field of Object.keys(modelDef.fields)) {
             if (isRelationField(this.schema, model, field)) {
                 continue;
             }
-            if (this.shouldOmitField(omit, model, field)) {
+            if (this.shouldOmitField(omit, model, field) && !depsNeeded.has(field)) {
+                continue;
+            }
+            // virtual fields don't exist in the database, skip them
+            const fieldDef = modelDef.fields[field];
+            if (fieldDef?.virtual) {
                 continue;
             }
             result = this.buildSelectField(result, model, modelAlias, field);
@@ -1143,9 +1168,11 @@ export abstract class BaseCrudDialect<Schema extends SchemaDef> {
             result = result.select((eb) => {
                 const jsonObject: Record<string, Expression<any>> = {};
                 for (const field of Object.keys(subModel.fields)) {
+                    const fieldDef = subModel.fields[field];
                     if (
                         isRelationField(this.schema, subModel.name, field) ||
-                        isInheritedField(this.schema, subModel.name, field)
+                        isInheritedField(this.schema, subModel.name, field) ||
+                        fieldDef?.virtual
                     ) {
                         continue;
                     }

packages/orm/src/client/crud/dialects/lateral-join-dialect-base.ts

@@ -204,13 +204,13 @@ export abstract class LateralJoinDialectBase<Schema extends SchemaDef> extends B
         }
 
         if (payload === true || !payload.select) {
-            // select all scalar fields except for omitted
+            // select all scalar fields except for omitted and virtual
             const omit = typeof payload === 'object' ? payload.omit : undefined;
 
             Object.assign(
                 objArgs,
                 ...Object.entries(relationModelDef.fields)
-                    .filter(([, value]) => !value.relation)
+                    .filter(([, value]) => !value.relation && !value.virtual)
                     .filter(([name]) => !this.shouldOmitField(omit, relationModel, name))
                     .map(([field]) => ({
                         [field]: this.fieldRef(relationModel, field, relationModelAlias, false),
@@ -233,14 +233,18 @@ export abstract class LateralJoinDialectBase<Schema extends SchemaDef> extends B
                             return { [field]: subJson };
                         } else {
                             const fieldDef = requireField(this.schema, relationModel, field);
+                            if (fieldDef.virtual) {
+                                return null;
+                            }
                             const fieldValue = fieldDef.relation
                                 ? // reference the synthesized JSON field
                                   eb.ref(`${parentResultName}$${field}.$data`)
                                 : // reference a plain field
                                   this.fieldRef(relationModel, field, relationModelAlias, false);
                             return { [field]: fieldValue };
                         }
-                    }),
+                    })
+                    .filter((v) => v !== null),
             );
         }
 

packages/orm/src/client/crud/dialects/sqlite.ts

@@ -253,7 +253,7 @@ export class SqliteCrudDialect<Schema extends SchemaDef> extends BaseCrudDialect
                 const omit = typeof payload === 'object' ? payload.omit : undefined;
                 objArgs.push(
                     ...Object.entries(relationModelDef.fields)
-                        .filter(([, value]) => !value.relation)
+                        .filter(([, value]) => !value.relation && !value.virtual)
                         .filter(([name]) => !this.shouldOmitField(omit, relationModel, name))
                         .map(([field]) => [sql.lit(field), this.fieldRef(relationModel, field, subQueryName, false)])
                         .flatMap((v) => v),
@@ -283,6 +283,8 @@ export class SqliteCrudDialect<Schema extends SchemaDef> extends BaseCrudDialect
                                         value,
                                     );
                                     return [sql.lit(field), subJson];
+                                } else if (fieldDef.virtual) {
+                                    return null;
                                 } else {
                                     return [
                                         sql.lit(field),
@@ -291,6 +293,7 @@ export class SqliteCrudDialect<Schema extends SchemaDef> extends BaseCrudDialect
                                 }
                             }
                         })
+                        .filter((v) => v !== null)
                         .flatMap((v) => v),
                 );
             }

packages/orm/src/client/crud/operations/base.ts

@@ -322,6 +322,23 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
         parentAlias: string,
     ) {
         let result = query;
+        let hasNonVirtualField = false;
+
+        // Collect dependency fields needed by selected virtual fields
+        const injectedDependencies = new Set<string>();
+        for (const [field, payload] of Object.entries(selectOrInclude)) {
+            if (!payload) continue;
+            const fieldDef = this.requireModel(model).fields[field];
+            const deps =
+                typeof fieldDef?.virtual === 'object' ? fieldDef.virtual.dependencies : undefined;
+            if (deps) {
+                for (const dep of deps) {
+                    if (!selectOrInclude[dep]) {
+                        injectedDependencies.add(dep);
+                    }
+                }
+            }
+        }
 
         for (const [field, payload] of Object.entries(selectOrInclude)) {
             if (!payload) {
@@ -330,13 +347,17 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
 
             if (field === '_count') {
                 result = this.buildCountSelection(result, model, parentAlias, payload);
+                hasNonVirtualField = true;
                 continue;
             }
 
             const fieldDef = this.requireField(model, field);
             if (!fieldDef.relation) {
-                // scalar field
-                result = this.dialect.buildSelectField(result, model, parentAlias, field);
+                // scalar field - skip virtual fields as they're computed at runtime
+                if (!fieldDef.virtual) {
+                    result = this.dialect.buildSelectField(result, model, parentAlias, field);
+                    hasNonVirtualField = true;
+                }
             } else {
                 if (!fieldDef.array && !fieldDef.optional && payload.where) {
                     throw createInternalError(`Field "${field}" does not support filtering`, model);
@@ -353,9 +374,20 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
                     //  regular relation
                     result = this.dialect.buildRelationSelection(result, model, field, parentAlias, payload);
                 }
+                hasNonVirtualField = true;
             }
         }
 
+        // Add injected dependency fields to the SQL SELECT
+        for (const dep of injectedDependencies) {
+            result = this.dialect.buildSelectField(result, model, parentAlias, dep);
+            hasNonVirtualField = true;
+        }
+
+        if (!hasNonVirtualField) {
+            throw createInvalidInputError('Cannot select only virtual fields', model);
+        }
+
         return result;
     }
 
@@ -1306,9 +1338,10 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
                     // collect id field/values from the original filter
                     const idFields = requireIdFields(this.schema, model);
                     const filterIdValues: any = {};
+                    const whereRecord = combinedWhere as Record<string, unknown>;
                     for (const key of idFields) {
-                        if (combinedWhere[key] !== undefined && typeof combinedWhere[key] !== 'object') {
-                            filterIdValues[key] = combinedWhere[key];
+                        if (whereRecord[key] !== undefined && typeof whereRecord[key] !== 'object') {
+                            filterIdValues[key] = whereRecord[key];
                         }
                     }
 
@@ -2554,6 +2587,9 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
         const computedFields = Object.values(modelDef.fields)
             .filter((f) => f.computed)
             .map((f) => f.name);
+        const virtualFields = Object.values(modelDef.fields)
+            .filter((f) => f.virtual)
+            .map((f) => f.name);
 
         const allFieldsSelected: string[] = [];
 
@@ -2573,8 +2609,12 @@ export abstract class BaseOperationHandler<Schema extends SchemaDef> {
             );
         }
 
-        if (allFieldsSelected.some((f) => relationFields.includes(f) || computedFields.includes(f))) {
-            // relation or computed field selected, need read back
+        if (
+            allFieldsSelected.some(
+                (f) => relationFields.includes(f) || computedFields.includes(f) || virtualFields.includes(f),
+            )
+        ) {
+            // relation, computed, or virtual field selected - need read back
             return { needReadBack: true, selectedFields: undefined };
         } else {
             return { needReadBack: false, selectedFields: allFieldsSelected };

packages/orm/src/client/crud/validator/index.ts

@@ -1236,7 +1236,7 @@ export class InputValidator<Schema extends SchemaDef> {
                 return;
             }
             const fieldDef = requireField(this.schema, model, field);
-            if (fieldDef.computed) {
+            if (fieldDef.computed || fieldDef.virtual) {
                 return;
             }
 
@@ -1557,6 +1557,9 @@ export class InputValidator<Schema extends SchemaDef> {
                 return;
             }
             const fieldDef = requireField(this.schema, model, field);
+            if (fieldDef.computed || fieldDef.virtual) {
+                return;
+            }
 
             if (fieldDef.relation) {
                 if (withoutRelationFields) {

packages/orm/src/client/helpers/schema-db-pusher.ts

@@ -115,7 +115,7 @@ export class SchemaDbPusher<Schema extends SchemaDef> {
 
             if (fieldDef.relation) {
                 table = this.addForeignKeyConstraint(table, modelDef.name, fieldName, fieldDef);
-            } else if (!this.isComputedField(fieldDef)) {
+            } else if (!this.isComputedField(fieldDef) && !this.isVirtualField(fieldDef)) {
                 table = this.createModelField(table, fieldDef, modelDef);
             }
         }
@@ -175,6 +175,10 @@ export class SchemaDbPusher<Schema extends SchemaDef> {
         return fieldDef.attributes?.some((a) => a.name === '@computed');
     }
 
+    private isVirtualField(fieldDef: FieldDef) {
+        return fieldDef.attributes?.some((a) => a.name === '@virtual');
+    }
+
     private addPrimaryKeyConstraint(table: CreateTableBuilder<string, any>, modelDef: ModelDef) {
         if (modelDef.idFields.length === 1) {
             if (Object.values(modelDef.fields).some((f) => f.id)) {