feat(orm): add support for runtime virtual fields

packages/language/res/stdlib.zmodel

@@ -643,6 +643,11 @@ attribute @json() @@@targetField([TypeDefField])
  */
 attribute @computed()
 
+/**
+ * Marks a field to be virtual
+ */
+attribute @virtual()
+
 /**
  * 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, client.$auth);
                 } else {
                     result = r ?? null;
                 }

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

@@ -23,6 +23,8 @@ import type {
     GetTypeDefs,
     ModelFieldIsOptional,
     NonRelationFields,
+    NonVirtualFields,
+    NonVirtualNonRelationFields,
     ProcedureDef,
     RelationFields,
     RelationFieldType,
@@ -281,7 +283,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 +758,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
               | {

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

@@ -1133,6 +1133,11 @@ export abstract class BaseCrudDialect<Schema extends SchemaDef> {
             if (this.shouldOmitField(omit, model, 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 +1148,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

@@ -1306,9 +1306,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];
                         }
                     }
 

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;
             }
 

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)) {

packages/orm/src/client/options.ts

@@ -1,7 +1,7 @@
 import type { Dialect, Expression, ExpressionBuilder, KyselyConfig } from 'kysely';
 import type { GetModel, GetModelFields, GetModels, ProcedureDef, ScalarFields, SchemaDef } from '../schema';
 import type { PrependParameter } from '../utils/type-utils';
-import type { ClientContract, CRUD_EXT } from './contract';
+import type { AuthType, ClientContract, CRUD_EXT } from './contract';
 import type { GetProcedureNames, ProcedureHandlerFunc } from './crud-types';
 import type { BaseCrudDialect } from './crud/dialects/base-dialect';
 import type { AnyPlugin } from './plugin';
@@ -101,6 +101,14 @@ export type ClientOptions<Schema extends SchemaDef> = {
           computedFields: ComputedFieldsOptions<Schema>;
       }
     : {}) &
+    (HasVirtualFields<Schema> extends true
+        ? {
+              /**
+               * Virtual field definitions (computed at runtime in JavaScript).
+               */
+              virtualFields: VirtualFieldsOptions<Schema>;
+          }
+        : {}) &
     (HasProcedures<Schema> extends true
         ? {
               /**
@@ -131,6 +139,33 @@ export type ComputedFieldsOptions<Schema extends SchemaDef> = {
 export type HasComputedFields<Schema extends SchemaDef> =
     string extends GetModels<Schema> ? false : keyof ComputedFieldsOptions<Schema> extends never ? false : true;
 
+/**
+ * Context passed to virtual field functions.
+ */
+export type VirtualFieldContext<Schema extends SchemaDef> = {
+    /**
+     * The current authenticated user, if set via `$setAuth()`.
+     */
+    auth: AuthType<Schema> | undefined;
+};
+
+/**
+ * Function that computes a virtual field value at runtime.
+ */
+export type VirtualFieldFunction<Schema extends SchemaDef = SchemaDef> = (
+    row: Record<string, unknown>,
+    context: VirtualFieldContext<Schema>,
+) => unknown | Promise<unknown>;
+
+export type VirtualFieldsOptions<Schema extends SchemaDef> = {
+    [Model in GetModels<Schema> as 'virtualFields' extends keyof GetModel<Schema, Model> ? Model : never]: {
+        [Field in keyof Schema['models'][Model]['virtualFields']]: VirtualFieldFunction<Schema>;
+    };
+};
+
+export type HasVirtualFields<Schema extends SchemaDef> =
+    string extends GetModels<Schema> ? false : keyof VirtualFieldsOptions<Schema> extends never ? false : true;
+
 export type ProceduresOptions<Schema extends SchemaDef> = Schema extends {
     procedures: Record<string, ProcedureDef>;
 }

packages/orm/src/client/result-processor.ts

@@ -1,36 +1,44 @@
 import type { BuiltinType, FieldDef, GetModels, SchemaDef } from '../schema';
 import { DELEGATE_JOINED_FIELD_PREFIX } from './constants';
+import type { AuthType } from './contract';
 import { getCrudDialect } from './crud/dialects';
 import type { BaseCrudDialect } from './crud/dialects/base-dialect';
-import type { ClientOptions } from './options';
+import type { ClientOptions, VirtualFieldContext, VirtualFieldFunction } from './options';
 import { ensureArray, getField, getIdValues } from './query-utils';
 
 export class ResultProcessor<Schema extends SchemaDef> {
     private dialect: BaseCrudDialect<Schema>;
+    private readonly virtualFieldsOptions: Record<string, Record<string, VirtualFieldFunction>> | undefined;
+
     constructor(
         private readonly schema: Schema,
         options: ClientOptions<Schema>,
     ) {
         this.dialect = getCrudDialect(schema, options);
+        this.virtualFieldsOptions = (options as any).virtualFields;
     }
 
-    processResult(data: any, model: GetModels<Schema>, args?: any) {
-        const result = this.doProcessResult(data, model);
+    async processResult(data: any, model: GetModels<Schema>, args?: any, auth?: AuthType<Schema>) {
+        const result = await this.doProcessResult(data, model, args, auth);
         // deal with correcting the reversed order due to negative take
         this.fixReversedResult(result, model, args);
         return result;
     }
 
-    private doProcessResult(data: any, model: GetModels<Schema>) {
+    private async doProcessResult(data: any, model: GetModels<Schema>, args?: any, auth?: AuthType<Schema>) {
         if (Array.isArray(data)) {
-            data.forEach((row, i) => (data[i] = this.processRow(row, model)));
+            await Promise.all(
+                data.map(async (row, i) => {
+                    data[i] = await this.processRow(row, model, args, auth);
+                }),
+            );
             return data;
         } else {
-            return this.processRow(data, model);
+            return this.processRow(data, model, args, auth);
         }
     }
 
-    private processRow(data: any, model: GetModels<Schema>) {
+    private async processRow(data: any, model: GetModels<Schema>, args?: any, auth?: AuthType<Schema>) {
         if (!data || typeof data !== 'object') {
             return data;
         }
@@ -59,7 +67,7 @@ export class ResultProcessor<Schema extends SchemaDef> {
                         delete data[key];
                         continue;
                     }
-                    const processedSubRow = this.processRow(subRow, subModel);
+                    const processedSubRow = await this.processRow(subRow, subModel, args, auth);
 
                     // merge the sub-row into the main row
                     Object.assign(data, processedSubRow);
@@ -82,11 +90,14 @@ export class ResultProcessor<Schema extends SchemaDef> {
             }
 
             if (fieldDef.relation) {
-                data[key] = this.processRelation(value, fieldDef);
+                data[key] = await this.processRelation(value, fieldDef, args, auth);
             } else {
                 data[key] = this.processFieldValue(value, fieldDef);
             }
         }
+
+        await this.applyVirtualFields(data, model, args, auth);
+
         return data;
     }
 
@@ -100,7 +111,7 @@ export class ResultProcessor<Schema extends SchemaDef> {
         }
     }
 
-    private processRelation(value: unknown, fieldDef: FieldDef) {
+    private async processRelation(value: unknown, fieldDef: FieldDef, args?: any, auth?: AuthType<Schema>) {
         let relationData = value;
         if (typeof value === 'string') {
             // relation can be returned as a JSON string
@@ -110,7 +121,48 @@ export class ResultProcessor<Schema extends SchemaDef> {
                 return value;
             }
         }
-        return this.doProcessResult(relationData, fieldDef.type as GetModels<Schema>);
+        return this.doProcessResult(relationData, fieldDef.type as GetModels<Schema>, args, auth);
+    }
+
+    private async applyVirtualFields(data: any, model: GetModels<Schema>, args?: any, auth?: AuthType<Schema>) {
+        if (!data || typeof data !== 'object') {
+            return;
+        }
+
+        const modelDef = this.schema.models[model as string];
+        if (!modelDef?.virtualFields || !this.virtualFieldsOptions) {
+            return;
+        }
+
+        const modelVirtualFieldOptions = this.virtualFieldsOptions[model as string];
+        if (!modelVirtualFieldOptions) {
+            return;
+        }
+
+        const virtualFieldNames = Object.keys(modelDef.virtualFields);
+        const selectClause = args?.select;
+        const omitClause = args?.omit;
+
+        // Build the context once for all virtual fields
+        const context: VirtualFieldContext<Schema> = { auth };
+
+        await Promise.all(
+            virtualFieldNames.map(async (fieldName) => {
+                // Skip if select clause exists and doesn't include this virtual field
+                if (selectClause && !selectClause[fieldName]) {
+                    return;
+                }
+
+                // Skip if omit clause includes this virtual field
+                if (omitClause?.[fieldName]) {
+                    return;
+                }
+
+                const virtualFn = modelVirtualFieldOptions[fieldName]!;
+
+                data[fieldName] = await virtualFn({ ...data }, context);
+            }),
+        );
     }
 
     private fixReversedResult(data: any, model: GetModels<Schema>, args: any) {