@opensaas/stack-core 0.38.0 → 0.39.1

package/dist/fields/index.js

@@ -3,18 +3,11 @@ import { hashPassword, isHashedPassword, HashedPassword } from '../utils/passwor
 import { formatPrismaDefault } from './format-prisma-default.js';
 import { getLabelFieldName } from '../config/label.js';
 import { RELATIONSHIP_COUNT_FILTER_KEY } from '../filter/types.js';
-/**
- * Operators shared by numeric/date fields: plain equality plus the four
- * comparisons. `eq` maps to Prisma's `equals`; the comparisons pass through.
- */
+/** Operators shared by numeric/date fields' `getFilterSpec`. */
 const COMPARISON_OPERATORS = ['eq', 'gt', 'gte', 'lt', 'lte'];
-/** Map a Filter operator to its Prisma condition key (`eq` → `equals`). */
 function prismaComparisonKey(operator) {
     return operator === 'eq' ? 'equals' : operator;
 }
-/**
- * Format field name for display in error messages
- */
 function formatFieldName(fieldName) {
     return fieldName
         .replace(/([A-Z])/g, ' $1')
@@ -59,11 +52,9 @@ export function text(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Native type modifier (e.g., @db.Text)
             if (db?.nativeType) {
                 modifiers += ` @db.${db.nativeType}`;
             }
@@ -88,7 +79,6 @@ export function text(options) {
             if (options?.isIndexed === 'unique') {
                 modifiers += ' @unique';
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -106,9 +96,6 @@ export function text(options) {
                 optional: !isRequired,
             };
         },
-        // Text fields drive free-text search: a bare word (or a `field:value`) maps
-        // to a case-preserving `contains`. This is what replaces the old hard-coded
-        // `type === 'text'` search in the admin list view.
         getFilterSpec: (fieldName) => ({
             operators: ['eq'],
             freeText: true,
@@ -148,21 +135,16 @@ export function integer(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Native type modifier (e.g., @db.SmallInt, @db.BigInt)
             if (db?.nativeType) {
                 modifiers += ` @db.${db.nativeType}`;
             }
-            // Default value if provided (bare numeric literal). Independent of the
-            // nullable `?` modifier above — the default never overwrites nullability.
             const defaultLiteral = formatPrismaDefault(options?.defaultValue, 'integer');
             if (defaultLiteral !== undefined) {
                 modifiers += ` @default(${defaultLiteral})`;
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -178,8 +160,7 @@ export function integer(options) {
                 optional: !isRequired,
             };
         },
-        // Integers support equality and comparisons (`orders:>5`). A non-integer
-        // value can't be interpreted, so its token degrades to free text.
+        // A non-integer token can't be interpreted, so it degrades to free text.
         getFilterSpec: (fieldName) => ({
             operators: COMPARISON_OPERATORS,
             toCondition: (operator, value) => {
@@ -244,8 +225,6 @@ export function decimal(options) {
         scale,
         ...options,
         getZodSchema: (fieldName, operation) => {
-            // Decimal values can be provided as strings or numbers
-            // Prisma will convert them to Decimal instances
             const baseSchema = z.union([
                 z.string({
                     message: `${formatFieldName(fieldName)} must be a decimal value (string or number)`,
@@ -257,7 +236,6 @@ export function decimal(options) {
                 message: `${formatFieldName(fieldName)} must be a decimal value`,
             });
             let schema = baseSchema;
-            // Add min validation if specified
             if (options?.validation?.min !== undefined) {
                 const minValue = parseFloat(options.validation.min);
                 schema = schema.refine((val) => {
@@ -267,7 +245,6 @@ export function decimal(options) {
                     message: `${formatFieldName(fieldName)} must be at least ${options.validation.min}`,
                 });
             }
-            // Add max validation if specified
             if (options?.validation?.max !== undefined) {
                 const maxValue = parseFloat(options.validation.max);
                 schema = schema.refine((val) => {
@@ -287,23 +264,18 @@ export function decimal(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Precision and scale
             modifiers += ` @db.Decimal(${precision}, ${scale})`;
-            // Default value if provided
             if (options?.defaultValue !== undefined) {
                 modifiers += ` @default(${options.defaultValue})`;
             }
-            // Database mapping
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
-            // Unique modifier. A non-unique index has no field-level form in Prisma,
-            // so it is requested out-of-line via `index` below and emitted by the
-            // generator as `@@index([...])` on the model.
+            // Unique modifier — non-unique index routes through `index` below,
+            // same as `text()`'s getPrismaType.
             if (options?.isIndexed === 'unique') {
                 modifiers += ' @unique';
             }
@@ -346,6 +318,116 @@ export function decimal(options) {
         }),
     };
 }
+/**
+ * 64-bit integer field for values that overflow `integer()`'s 32-bit `Int`
+ * (e.g. a millisecond epoch). Prisma `BigInt`, TypeScript `bigint`.
+ *
+ * Accepts `bigint`, an integer `number`, or a numeric `string` on write and
+ * always coerces to `bigint`. A `number` above `Number.MAX_SAFE_INTEGER` is
+ * rejected rather than coerced — it has already lost precision before this
+ * field sees it, so accepting it would reintroduce the exact defect this
+ * field exists to prevent. Pass a `bigint` or a string for values beyond that
+ * range.
+ *
+ * Wire representation (ADR-0029): `bigint` in application code, a decimal
+ * string over MCP.
+ */
+export function bigInt(options) {
+    return {
+        type: 'bigInt',
+        ...options,
+        getZodSchema: (fieldName, operation) => {
+            const validation = options?.validation;
+            const isRequired = validation?.isRequired;
+            const coerced = z
+                .union([z.bigint(), z.number(), z.string()], {
+                message: `${formatFieldName(fieldName)} must be a bigint, an integer number, or a numeric string`,
+            })
+                .transform((val, ctx) => {
+                if (typeof val === 'bigint')
+                    return val;
+                if (typeof val === 'number') {
+                    if (!Number.isInteger(val)) {
+                        ctx.addIssue(`${formatFieldName(fieldName)} must be an integer`);
+                        return z.NEVER;
+                    }
+                    if (!Number.isSafeInteger(val)) {
+                        ctx.addIssue(`${formatFieldName(fieldName)} exceeds Number.MAX_SAFE_INTEGER — pass a bigint or a numeric string instead`);
+                        return z.NEVER;
+                    }
+                    return BigInt(val);
+                }
+                const trimmed = val.trim();
+                if (!/^-?\d+$/.test(trimmed)) {
+                    ctx.addIssue(`${formatFieldName(fieldName)} must be an integer`);
+                    return z.NEVER;
+                }
+                return BigInt(trimmed);
+            });
+            let schema = coerced;
+            if (validation?.min !== undefined) {
+                const min = validation.min;
+                schema = schema.refine((val) => val >= min, {
+                    message: `${formatFieldName(fieldName)} must be at least ${min}`,
+                });
+            }
+            if (validation?.max !== undefined) {
+                const max = validation.max;
+                schema = schema.refine((val) => val <= max, {
+                    message: `${formatFieldName(fieldName)} must be at most ${max}`,
+                });
+            }
+            return !isRequired || operation === 'update' ? schema.optional().nullable() : schema;
+        },
+        getPrismaType: (_fieldName) => {
+            const validation = options?.validation;
+            const db = options?.db;
+            const isRequired = validation?.isRequired;
+            const isNullable = db?.isNullable ?? !isRequired;
+            let modifiers = '';
+            if (isNullable) {
+                modifiers += '?';
+            }
+            if (db?.nativeType) {
+                modifiers += ` @db.${db.nativeType}`;
+            }
+            if (options?.defaultValue !== undefined) {
+                modifiers += ` @default(${options.defaultValue})`;
+            }
+            if (db?.map) {
+                modifiers += ` @map("${db.map}")`;
+            }
+            // Unique modifier — non-unique index routes through `index` below,
+            // same as `text()`'s getPrismaType.
+            if (options?.isIndexed === 'unique') {
+                modifiers += ' @unique';
+            }
+            return {
+                type: 'BigInt',
+                modifiers: modifiers.trimStart() || undefined,
+                index: options?.isIndexed === true ? true : undefined,
+            };
+        },
+        getTypeScriptType: () => {
+            const isRequired = options?.validation?.isRequired;
+            return {
+                type: 'bigint',
+                optional: !isRequired,
+            };
+        },
+        // A non-integer token degrades to free text.
+        getFilterSpec: (fieldName) => ({
+            operators: COMPARISON_OPERATORS,
+            toCondition: (operator, value) => {
+                const trimmed = value.trim();
+                if (!/^-?\d+$/.test(trimmed))
+                    return null;
+                return { [fieldName]: { [prismaComparisonKey(operator)]: BigInt(trimmed) } };
+            },
+            suggestions: { valueSource: { kind: 'none' } },
+        }),
+    };
+}
 /**
  * Checkbox (boolean) field
  */
@@ -360,15 +442,15 @@ export function checkbox(options) {
             const db = options?.db;
             const hasDefault = options?.defaultValue !== undefined;
             let modifiers = '';
-            // Nullable modifier - checkbox fields are non-nullable by default (must be true or false)
-            // Use db.isNullable: true to allow NULL values in the database
+            // Checkboxes are non-nullable by default (must be true or false), unlike
+            // the other scalar fields' nullable-unless-required default — set
+            // db.isNullable: true to allow NULL.
             if (db?.isNullable === true) {
                 modifiers += '?';
             }
             if (hasDefault) {
                 modifiers += ` @default(${options.defaultValue})`;
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -383,8 +465,7 @@ export function checkbox(options) {
                 optional: options?.defaultValue === undefined,
             };
         },
-        // Checkboxes filter by equality against the two enumerated values. Anything
-        // other than true/false can't be interpreted and degrades to free text.
+        // Anything other than true/false degrades to free text.
         getFilterSpec: (fieldName) => ({
             operators: ['eq'],
             toCondition: (operator, value) => {
@@ -425,22 +506,17 @@ export function timestamp(options) {
                 typeof options.defaultValue === 'object' &&
                 'kind' in options.defaultValue &&
                 options.defaultValue.kind === 'now';
-            // Nullability: explicit db.isNullable overrides the default (nullable unless @default(now()))
             const isNullable = db?.isNullable ?? !hasDefaultNow;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Default value
             if (hasDefaultNow) {
                 modifiers += ' @default(now())';
             }
-            // Native type modifier (e.g., @db.Timestamptz for PostgreSQL)
             if (db?.nativeType) {
                 modifiers += ` @db.${db.nativeType}`;
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -459,8 +535,7 @@ export function timestamp(options) {
                 optional: !hasDefault,
             };
         },
-        // Timestamps support equality and comparisons (`joined:>2024-01-01`). An
-        // unparseable date degrades to free text.
+        // An unparseable date degrades to free text.
         getFilterSpec: (fieldName) => ({
             operators: COMPARISON_OPERATORS,
             toCondition: (operator, value) => {
@@ -537,23 +612,11 @@ export function calendarDay(options) {
     return {
         type: 'calendarDay',
         ...options,
-        // Writes: the write pipeline runs field resolveInput BEFORE zod
-        // validation (Hook Pipeline: field resolveInput → built-in field rules),
-        // so this is the only point a YYYY-MM-DD string can be turned into
-        // something Prisma's `@db.Date` write validator accepts — Prisma 7
-        // rejects a bare date string there (#621). Convert a valid string to a
-        // UTC-midnight Date; leave anything else (a Date already, null/undefined,
-        // or a malformed string) untouched so the zod schema below still rejects
-        // malformed input with a clear message. Reads resolvedData[fieldKey]
-        // (not raw inputData) so a list-level resolveInput that injects a default
-        // for an omitted key is still coerced instead of being overwritten.
-        //
-        // Reads: the underlying @db.Date column hands Prisma a Date (or a TEXT
-        // string under the SQLite fallback). Normalise to a YYYY-MM-DD string so the
-        // runtime value matches the declared `string` type. UTC components are used
-        // so the formatting never drifts a day in non-UTC timezones.
-        // Cast hooks to any since field builders are generic and can't know the
-        // specific TFieldKey (same pattern as password()).
+        // Hook Pipeline runs field resolveInput before zod validation — the only
+        // point a YYYY-MM-DD string can be turned into what Prisma's `@db.Date`
+        // write validator accepts (#621). Reads resolvedData[fieldKey], not raw
+        // inputData, so a list-level resolveInput's injected default for an
+        // omitted key is still coerced rather than overwritten.
         hooks: {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
             resolveInput: ({ resolvedData, fieldKey }) => {
@@ -567,17 +630,15 @@ export function calendarDay(options) {
             },
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
             resolveOutput: ({ value }) => formatCalendarDay(value),
-            // Merge with user-provided hooks if any
             ...options?.hooks,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hook object needs type assertion for field builder
         },
         getZodSchema: (fieldName, operation) => {
             const validation = options?.validation;
             const isRequired = validation?.isRequired;
-            // Accept ISO8601 date strings (YYYY-MM-DD) in the shape a caller passes,
-            // or a `Date` — the shape resolveInput above turns a valid string into
-            // before this schema runs. Malformed strings fall through resolveInput
-            // untouched and still fail the regex here with a clear message.
+            // Accepts a `Date` because resolveInput above already converted a valid
+            // string to one before this schema runs; a malformed string falls
+            // through resolveInput untouched and fails the regex here instead.
             const stringSchema = z
                 .string({
                 message: `${formatFieldName(fieldName)} must be a valid date in ISO8601 format (YYYY-MM-DD)`,
@@ -590,7 +651,6 @@ export function calendarDay(options) {
                 return dateSchema;
             }
             else if (isRequired && operation === 'update') {
-                // Required in update mode: omitted keys pass; present values must be valid
                 return dateSchema.optional();
             }
             else {
@@ -603,27 +663,22 @@ export function calendarDay(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Add @db.Date attribute for date-only storage
-            // Only for PostgreSQL/MySQL - SQLite doesn't support native DATE type
-            // SQLite will use TEXT for DateTime fields
+            // SQLite has no native DATE type and falls back to TEXT for DateTime
+            // columns, so @db.Date only applies on PostgreSQL/MySQL.
             if (provider && provider.toLowerCase() !== 'sqlite') {
                 modifiers += ' @db.Date';
             }
-            // Default value if provided
             if (options?.defaultValue !== undefined) {
                 modifiers += ` @default("${options.defaultValue}")`;
             }
-            // Database mapping
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
-            // Unique modifier. A non-unique index has no field-level form in Prisma,
-            // so it is requested out-of-line via `index` below and emitted by the
-            // generator as `@@index([...])` on the model.
+            // Unique modifier — non-unique index routes through `index` below,
+            // same as `text()`'s getPrismaType.
             if (options?.isIndexed === 'unique') {
                 modifiers += ' @unique';
             }
@@ -638,12 +693,6 @@ export function calendarDay(options) {
             const db = options?.db;
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
-            // calendarDay is a YYYY-MM-DD string end-to-end (Keystone's CalendarDay
-            // scalar). Returning 'string' here makes the entity/read type and the
-            // standalone generated CreateInput/UpdateInput types `string`. At the
-            // context.db write path a Date is still rejected at runtime by validation
-            // (the generated db method `data` type derives from Prisma's `Date | string`
-            // input — making it a compile-time error is tracked in #599).
             return {
                 type: 'string',
                 optional: isNullable,
@@ -749,43 +798,34 @@ export function password(options) {
         ...options,
         resultExtension: {
             outputType: "import('@opensaas/stack-core/internal').HashedPassword",
-            // No compute - delegates to resolveOutput hook
         },
         ui: {
             ...options?.ui,
             valueForClientSerialization: ({ value }) => ({ isSet: !!value }),
         },
-        // Cast hooks to any since field builders are generic and can't know the specific TFieldKey
         hooks: {
-            // Hash password before writing to database
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
             resolveInput: async ({ inputData, fieldKey }) => {
-                // Skip if undefined or null (allows partial updates)
                 const inputValue = inputData[fieldKey];
                 if (inputValue === undefined || inputValue === null) {
                     return inputValue;
                 }
-                // Skip if not a string
                 if (typeof inputValue !== 'string' || inputValue.length === 0) {
                     return inputValue;
                 }
-                // Skip if already hashed (idempotent)
+                // Idempotent: skip re-hashing a value that's already a hash.
                 if (isHashedPassword(inputValue)) {
                     return inputValue;
                 }
-                // Hash the password
                 return (await hashPassword(inputValue)).toString();
             },
-            // Wrap password with HashedPassword class after reading from database
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Field builder hooks must be generic
             resolveOutput: ({ value }) => {
-                // Only wrap string values (hashed passwords)
                 if (typeof value === 'string' && value.length > 0) {
                     return new HashedPassword(value);
                 }
                 return undefined;
             },
-            // Merge with user-provided hooks if any
             ...options?.hooks,
             // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Hook object needs type assertion for field builder
         },
@@ -793,7 +833,6 @@ export function password(options) {
             const validation = options?.validation;
             const isRequired = validation?.isRequired;
             if (isRequired && operation === 'create') {
-                // Required in create mode: reject undefined and empty strings
                 return z
                     .string({
                     message: `${formatFieldName(fieldName)} must be text`,
@@ -803,7 +842,6 @@ export function password(options) {
                 });
             }
             else if (isRequired && operation === 'update') {
-                // Required in update mode: omitted keys pass; if provided, reject empty strings
                 return z
                     .string()
                     .min(1, {
@@ -812,7 +850,6 @@ export function password(options) {
                     .optional();
             }
             else {
-                // Not required: can be undefined or any string
                 return z
                     .string({
                     message: `${formatFieldName(fieldName)} must be text`,
@@ -827,15 +864,12 @@ export function password(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Native type modifier (e.g., @db.Text)
             if (db?.nativeType) {
                 modifiers += ` @db.${db.nativeType}`;
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -900,7 +934,6 @@ export function select(options) {
             // (mirroring text/integer) so the default never overwrites the `?`.
             const isNullable = options.db?.isNullable ?? (!isRequired && !hasDefault);
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
@@ -911,11 +944,10 @@ export function select(options) {
                 const capitalizedField = fieldName.charAt(0).toUpperCase() + fieldName.slice(1);
                 const derivedEnumName = listName ? `${listName}${capitalizedField}` : capitalizedField;
                 const enumName = options.db?.enumName ?? derivedEnumName;
-                // Add default value if provided (no quotes for enum values)
+                // No quotes for enum default values (unlike the string branch below).
                 if (hasDefault) {
                     modifiers += ` @default(${options.defaultValue})`;
                 }
-                // Map modifier
                 if (options.db?.map) {
                     modifiers += ` @map("${options.db.map}")`;
                 }
@@ -926,11 +958,9 @@ export function select(options) {
                 };
             }
             // String type (default)
-            // Add default value if provided
             if (hasDefault) {
                 modifiers += ` @default("${options.defaultValue}")`;
             }
-            // Map modifier
             if (options.db?.map) {
                 modifiers += ` @map("${options.db.map}")`;
             }
@@ -995,9 +1025,6 @@ function parseRelationshipRef(ref) {
         throw new Error(`Invalid relationship ref: ${ref}`);
     }
 }
-/**
- * Check if a relationship is one-to-one (bidirectional with both sides having many: false).
- */
 function isOneToOneRelationship(fieldName, field, config) {
     const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
     if (!targetField) {
@@ -1019,10 +1046,6 @@ function isOneToOneRelationship(fieldName, field, config) {
     }
     return !targetFieldConfig.many;
 }
-/**
- * Determine if this side of a relationship should store the foreign key.
- * For one-to-one relationships, only one side stores the foreign key.
- */
 function shouldHaveForeignKey(listKey, fieldName, field, config) {
     const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
     if (!targetField) {
@@ -1056,9 +1079,6 @@ function shouldHaveForeignKey(listKey, fieldName, field, config) {
     // Self-referential: use field name ordering
     return fieldName.localeCompare(targetField) < 0;
 }
-/**
- * Check whether a many relationship is a true many-to-many (both sides many).
- */
 function isManyToMany(fieldName, field, config) {
     if (!field.many) {
         return false;
@@ -1111,12 +1131,8 @@ function computeManyToManyRelationName(listKey, fieldName, field, config) {
         }
         return `${listKey}_${fieldName}`;
     }
-    // Default Prisma naming - no explicit relation name needed
     return undefined;
 }
-/**
- * Build the Prisma schema contribution for a relationship field.
- */
 function getPrismaRelation(field, fieldName, listKey, config) {
     const { list: targetList, field: targetField } = parseRelationshipRef(field.ref);
     const paddedName = fieldName.padEnd(12);
@@ -1203,27 +1219,20 @@ export function relationship(options) {
     if (!options.ref) {
         throw new Error('Relationship field must have a ref');
     }
-    // Validate ref format: 'ListName.fieldName' or 'ListName'
     const refParts = options.ref.split('.');
     if (refParts.length !== 1 && refParts.length !== 2) {
         throw new Error(`Invalid relationship ref format: "${options.ref}". Expected format: "ListName.fieldName" or "ListName"`);
     }
-    // Validate db.foreignKey usage
     if (options.db?.foreignKey !== undefined) {
-        // Can only be used on single relationships (not many)
         if (options.many) {
             throw new Error('db.foreignKey can only be used on single relationships (many: false or undefined). ' +
                 'Many-side of a relationship never stores the foreign key.');
         }
-        // Can only be used on bidirectional relationships (with target field)
         if (refParts.length === 1) {
             throw new Error('db.foreignKey can only be used on bidirectional relationships (ref: "ListName.fieldName"). ' +
                 'List-only refs (ref: "ListName") always create foreign keys automatically.');
         }
     }
-    // Validate db.isNullable usage: only the FK-owning (single) side of a
-    // relationship has a column to make non-nullable — the many side always
-    // generates an array field with no nullability of its own.
     if (options.db?.isNullable !== undefined && options.many) {
         throw new Error('db.isNullable can only be used on single relationships (many: false or undefined). ' +
             'Many-side of a relationship has no foreign key column to make non-nullable.');
@@ -1333,7 +1342,6 @@ export function json(options) {
         getZodSchema: (fieldName, operation) => {
             const validation = options?.validation;
             const isRequired = validation?.isRequired;
-            // Accept any valid JSON value
             const baseSchema = z.unknown();
             if (isRequired && operation === 'create') {
                 // Required in create mode: a value must be provided and it must be
@@ -1360,7 +1368,6 @@ export function json(options) {
                     .optional();
             }
             else {
-                // Not required: can be undefined or null
                 return baseSchema.optional().nullable();
             }
         },
@@ -1370,22 +1377,16 @@ export function json(options) {
             const isRequired = validation?.isRequired;
             const isNullable = db?.isNullable ?? !isRequired;
             let modifiers = '';
-            // Optional modifier
             if (isNullable) {
                 modifiers += '?';
             }
-            // Native type modifier
             if (db?.nativeType) {
                 modifiers += ` @db.${db.nativeType}`;
             }
-            // Default value if provided. Uses Keystone's JSON-literal form: canonical
-            // (space-free) JSON wrapped in escaped double quotes. Independent of the
-            // nullable `?` modifier above — the default never overwrites nullability.
             const defaultLiteral = formatPrismaDefault(options?.defaultValue, 'json');
             if (defaultLiteral !== undefined) {
                 modifiers += ` @default(${defaultLiteral})`;
             }
-            // Map modifier
             if (db?.map) {
                 modifiers += ` @map("${db.map}")`;
             }
@@ -1414,17 +1415,10 @@ function typeDescriptorToString(descriptor) {
     if (typeof descriptor === 'string') {
         return descriptor;
     }
-    // Extract type name from constructor or use provided name
     const typeName = descriptor.name || descriptor.value.name;
-    // Generate import string
     return `import('${descriptor.from}').${typeName}`;
 }
-/**
- * Extract TypeScript imports from a TypeDescriptor
- * Returns array of import statements needed for type generation
- */
 function typeDescriptorToImports(descriptor) {
-    // If it's a string, check if it's an import string
     if (typeof descriptor === 'string') {
         const importMatch = descriptor.match(/import\('([^']+)'\)\.(\w+)/);
         if (importMatch) {
@@ -1519,12 +1513,10 @@ function typeDescriptorToImports(descriptor) {
  * @returns Virtual field configuration
  */
 export function virtual(options) {
-    // Validate that resolveOutput is provided
     if (!options.hooks?.resolveOutput) {
         throw new Error('Virtual fields must provide a resolveOutput hook to compute their value. ' +
             'Example: hooks: { resolveOutput: ({ item }) => computeValue(item) }');
     }
-    // Convert type descriptor to string
     const outputType = typeDescriptorToString(options.type);
     const imports = typeDescriptorToImports(options.type);
     const { type: _, ...rest } = options;
@@ -1533,19 +1525,16 @@ export function virtual(options) {
         virtual: true,
         outputType,
         ...rest,
-        // Virtual fields don't create database columns
-        // Return undefined to signal generator to skip this field
+        // undefined signals the generator to skip creating a database column.
         getPrismaType: undefined,
-        // Virtual fields appear in output types with their specified type
         getTypeScriptType: () => {
             return {
                 type: outputType,
-                optional: false, // Virtual fields always compute a value
+                optional: false, // A virtual field always computes a value.
             };
         },
-        // Add import statements if needed
         getTypeScriptImports: imports.length > 0 ? () => imports : undefined,
-        // Virtual fields never validate input (they don't accept database input)
+        // Virtual fields don't accept database input, so validation always fails.
         getZodSchema: () => {
             return z.never();
         },