feat(orm): add result plugin extension point for computed query fields

Implement a new `result` extension point that allows plugins to declare computed
fields on query results with automatic type safety and select/omit awareness.

Changes:
- Add ExtResultFieldDef and ExtResultBase types to plugin.ts
- Add ExtResult generic parameter to RuntimePlugin, AnyPlugin, definePlugin
- Thread ExtResult through ClientContract and all CRUD return types
- Add ExtractExtResult, ExtResultSelectOmitFields, SelectAwareExtResult type helpers
- Implement recursive runtime computation in client-impl.ts with needs injection/stripping
- Add ext result fields to Zod validation for select/omit schemas
- Support nested relation ext result computation (both runtime and types)
- Add 26 comprehensive tests covering single-model and nested relation scenarios

Features:
- Type-safe computed fields on query results
- Select/omit-aware types (only include selected fields in result type)
- Automatic field dependency (needs) injection and stripping
- Multi-plugin composition support
- Full support for nested relations (include/select with ext results)
- Works with $transaction, $setAuth, $setOptions, etc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: genu

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

@@ -38,6 +38,7 @@ import * as BuiltinFunctions from './functions';
 import { SchemaDbPusher } from './helpers/schema-db-pusher';
 import type { ClientOptions, ProceduresOptions } from './options';
 import type { AnyPlugin } from './plugin';
+import { getField } from './query-utils';
 import { createZenStackPromise, type ZenStackPromise } from './promise';
 import { ResultProcessor } from './result-processor';
 
@@ -547,6 +548,11 @@ function createModelCrudHandler(
     inputValidator: InputValidator<any>,
     resultProcessor: ResultProcessor<any>,
 ): ModelOperations<any, any> {
+    // check if any plugin defines ext result fields
+    const plugins = client.$options.plugins ?? [];
+    const schema = client.$schema;
+    const hasAnyExtResult = hasExtResultDefs(plugins);
+
     const createPromise = (
         operation: CoreCrudOperations,
         nominalOperation: AllCrudOperations,
@@ -557,17 +563,30 @@ function createModelCrudHandler(
     ) => {
         return createZenStackPromise(async (txClient?: ClientContract<any>) => {
             let proceed = async (_args: unknown) => {
+                // prepare args for ext result: strip ext result field names from select/omit,
+                // inject needs fields into select (recursively handles nested relations)
+                const processedArgs =
+                    postProcess && hasAnyExtResult
+                        ? prepareArgsForExtResult(_args, model, schema, plugins)
+                        : _args;
+
                 const _handler = txClient ? handler.withClient(txClient) : handler;
-                const r = await _handler.handle(operation, _args);
+                const r = await _handler.handle(operation, processedArgs);
                 if (!r && throwIfNoResult) {
                     throw createNotFoundError(model);
                 }
                 let result: unknown;
                 if (r && postProcess) {
-                    result = resultProcessor.processResult(r, model, args);
+                    result = resultProcessor.processResult(r, model, processedArgs);
                 } else {
                     result = r ?? null;
                 }
+
+                // compute ext result fields (recursively handles nested relations)
+                if (result && postProcess && hasAnyExtResult) {
+                    result = applyExtResult(result, model, _args, schema, plugins);
+                }
+
                 return result;
             };
 
@@ -823,3 +842,247 @@ function createModelCrudHandler(
 
     return operations as ModelOperations<any, any>;
 }
+
+// #region Extended result field helpers
+
+type ExtResultDef = { needs: Record<string, true>; compute: (data: any) => unknown };
+
+/**
+ * Returns true if any plugin defines ext result fields for any model.
+ */
+function hasExtResultDefs(plugins: AnyPlugin[]): boolean {
+    return plugins.some((p) => p.result && Object.keys(p.result).length > 0);
+}
+
+/**
+ * Collects extended result field definitions from all plugins for a given model.
+ */
+function collectExtResultDefs(model: string, plugins: AnyPlugin[]): Map<string, ExtResultDef> {
+    const defs = new Map<string, ExtResultDef>();
+    for (const plugin of plugins) {
+        const resultConfig = plugin.result;
+        if (resultConfig) {
+            const modelConfig = resultConfig[model];
+            if (modelConfig) {
+                for (const [fieldName, fieldDef] of Object.entries(modelConfig)) {
+                    defs.set(fieldName, fieldDef as ExtResultDef);
+                }
+            }
+        }
+    }
+    return defs;
+}
+
+/**
+ * Prepares query args for extended result fields (recursive):
+ * - Strips ext result field names from `select` and `omit`
+ * - Injects `needs` fields into `select` when ext result fields are explicitly selected
+ * - Recurses into `include` and `select` for nested relation fields
+ */
+function prepareArgsForExtResult(
+    args: unknown,
+    model: string,
+    schema: SchemaDef,
+    plugins: AnyPlugin[],
+): unknown {
+    if (!args || typeof args !== 'object') {
+        return args;
+    }
+
+    const extResultDefs = collectExtResultDefs(model, plugins);
+    const typedArgs = args as Record<string, unknown>;
+    let result = typedArgs;
+    let changed = false;
+
+    const select = typedArgs['select'] as Record<string, unknown> | undefined;
+    const omit = typedArgs['omit'] as Record<string, unknown> | undefined;
+    const include = typedArgs['include'] as Record<string, unknown> | undefined;
+
+    if (select && extResultDefs.size > 0) {
+        const newSelect = { ...select };
+        for (const [fieldName, fieldDef] of extResultDefs) {
+            if (newSelect[fieldName]) {
+                delete newSelect[fieldName];
+                // inject needs fields
+                for (const needField of Object.keys(fieldDef.needs)) {
+                    if (!newSelect[needField]) {
+                        newSelect[needField] = true;
+                    }
+                }
+            }
+        }
+        result = { ...result, select: newSelect };
+        changed = true;
+    }
+
+    if (omit && extResultDefs.size > 0) {
+        const newOmit = { ...omit };
+        for (const fieldName of extResultDefs.keys()) {
+            if (newOmit[fieldName]) {
+                delete newOmit[fieldName];
+            }
+        }
+        result = { ...result, omit: newOmit };
+        changed = true;
+    }
+
+    // Recurse into nested relations in `include`
+    if (include) {
+        const newInclude = { ...include };
+        let includeChanged = false;
+        for (const [field, value] of Object.entries(newInclude)) {
+            if (value && typeof value === 'object') {
+                const fieldDef = getField(schema, model, field);
+                if (fieldDef?.relation) {
+                    const targetModel = fieldDef.type;
+                    const processed = prepareArgsForExtResult(value, targetModel, schema, plugins);
+                    if (processed !== value) {
+                        newInclude[field] = processed;
+                        includeChanged = true;
+                    }
+                }
+            }
+        }
+        if (includeChanged) {
+            result = changed ? { ...result, include: newInclude } : { ...typedArgs, include: newInclude };
+            changed = true;
+        }
+    }
+
+    // Recurse into nested relations in `select` (relation fields can have nested args)
+    if (select) {
+        const currentSelect = (changed ? (result as Record<string, unknown>)['select'] : select) as
+            | Record<string, unknown>
+            | undefined;
+        if (currentSelect) {
+            const newSelect = { ...currentSelect };
+            let selectChanged = false;
+            for (const [field, value] of Object.entries(newSelect)) {
+                if (value && typeof value === 'object') {
+                    const fieldDef = getField(schema, model, field);
+                    if (fieldDef?.relation) {
+                        const targetModel = fieldDef.type;
+                        const processed = prepareArgsForExtResult(value, targetModel, schema, plugins);
+                        if (processed !== value) {
+                            newSelect[field] = processed;
+                            selectChanged = true;
+                        }
+                    }
+                }
+            }
+            if (selectChanged) {
+                result = { ...result, select: newSelect };
+                changed = true;
+            }
+        }
+    }
+
+    return changed ? result : args;
+}
+
+/**
+ * Applies extended result field computation to query results (recursive).
+ * Processes the current model's ext result fields, then recurses into nested relation data.
+ */
+function applyExtResult(
+    result: unknown,
+    model: string,
+    originalArgs: unknown,
+    schema: SchemaDef,
+    plugins: AnyPlugin[],
+): unknown {
+    if (Array.isArray(result)) {
+        for (let i = 0; i < result.length; i++) {
+            result[i] = applyExtResultToRow(result[i], model, originalArgs, schema, plugins);
+        }
+        return result;
+    } else {
+        return applyExtResultToRow(result, model, originalArgs, schema, plugins);
+    }
+}
+
+function applyExtResultToRow(
+    row: unknown,
+    model: string,
+    originalArgs: unknown,
+    schema: SchemaDef,
+    plugins: AnyPlugin[],
+): unknown {
+    if (!row || typeof row !== 'object') {
+        return row;
+    }
+
+    const data = row as Record<string, unknown>;
+    const extResultDefs = collectExtResultDefs(model, plugins);
+    const typedArgs = (originalArgs && typeof originalArgs === 'object' ? originalArgs : {}) as Record<string, unknown>;
+    const select = typedArgs['select'] as Record<string, unknown> | undefined;
+    const omit = typedArgs['omit'] as Record<string, unknown> | undefined;
+    const include = typedArgs['include'] as Record<string, unknown> | undefined;
+
+    // Determine which ext result fields were selected/omitted at this level
+    const selectedExtResultFields = select ? new Set<string>() : undefined;
+    const omittedExtResultFields = omit ? new Set<string>() : undefined;
+    const injectedNeedsFields = new Set<string>();
+
+    if (select && extResultDefs.size > 0) {
+        for (const [fieldName, fieldDef] of extResultDefs) {
+            if (select[fieldName]) {
+                selectedExtResultFields!.add(fieldName);
+                // Track injected needs: fields that were NOT in the original select
+                for (const needField of Object.keys(fieldDef.needs)) {
+                    if (!select[needField]) {
+                        injectedNeedsFields.add(needField);
+                    }
+                }
+            }
+        }
+    }
+
+    if (omit && extResultDefs.size > 0) {
+        for (const fieldName of extResultDefs.keys()) {
+            if (omit[fieldName]) {
+                omittedExtResultFields!.add(fieldName);
+            }
+        }
+    }
+
+    // Compute ext result fields for the current model
+    for (const [fieldName, fieldDef] of extResultDefs) {
+        if (omittedExtResultFields?.has(fieldName)) {
+            continue;
+        }
+        if (selectedExtResultFields !== undefined && !selectedExtResultFields.has(fieldName)) {
+            continue;
+        }
+        const needsSatisfied = Object.keys(fieldDef.needs).every((needField) => needField in data);
+        if (needsSatisfied) {
+            data[fieldName] = fieldDef.compute(data);
+        }
+    }
+
+    // Strip injected needs fields that weren't originally requested
+    for (const field of injectedNeedsFields) {
+        delete data[field];
+    }
+
+    // Recurse into nested relation data
+    const relationSource = include ?? select;
+    if (relationSource) {
+        for (const [field, value] of Object.entries(relationSource)) {
+            if (data[field] == null) {
+                continue;
+            }
+            const fieldDef = getField(schema, model, field);
+            if (!fieldDef?.relation) {
+                continue;
+            }
+            const targetModel = fieldDef.type;
+            const nestedArgs = value && typeof value === 'object' ? value : undefined;
+            data[field] = applyExtResult(data[field], targetModel, nestedArgs, schema, plugins);
+        }
+    }
+
+    return data;
+}
+
+// #endregion