Fix: Flex field with object value threw an error

changelog.md

@@ -2,6 +2,12 @@
 
 📝 following beta format X.Y.Z where Y = breaking change and Z = feature and fix. Later => FAIL.FEATURE.FIX
 
+## 0.15.4(2026-02-17)
+
+- Fix: Plain object in flex field mutation threw an error
+- Fix: Array in flex field mutation threw an error
+- Tests: Added tests for flex fields with object values
+
 ## 0.15.3(2026-02-12)
 
 - Fix: Upgrade SurrealDB SDK to 2.0.0-alpha.18

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blitznocode/blitz-orm",
-  "version": "0.15.3",
+  "version": "0.15.4",
   "author": "blitznocode.com",
   "description": "Blitz-orm is an Object Relational Mapper (ORM) for graph databases that uses a JSON query language called Blitz Query Language (BQL). BQL is similar to GraphQL but uses JSON instead of strings. This makes it easier to build dynamic queries.",
   "main": "dist/index.mjs",
@@ -106,5 +106,5 @@
   "directories": {
     "test": "tests"
   },
-  "packageManager": "pnpm@8.10.2+sha512.0782093d5ba6c7ad9462081bc1ef0775016a4b4109eca1e1fedcea6f110143af5f50993db36c427d4fa8c62be3920a3224db12da719d246ca19dd9f18048c33c"
+  "packageManager": "pnpm@10.30.0"
 }

src/adapters/surrealDB/parsing/parseFlexVal.ts

@@ -18,5 +18,8 @@ export const parseFlexValSurrealDB = (v: unknown) => {
   if (['number', 'boolean'].includes(typeof v)) {
     return v;
   }
+  if (typeof v === 'object' && v !== null) {
+    return JSON.stringify(v);
+  }
   throw new Error(`Unsupported type ${typeof v}`);
 };

src/adapters/surrealDB/parsing/values.ts

@@ -1,4 +1,4 @@
-import { isArray, isDate } from 'radash';
+import { isDate } from 'radash';
 import { parseFlexValSurrealDB } from './parseFlexVal';
 
 export const surrealDBtypeMap: Record<string, string> = {
@@ -54,9 +54,7 @@ export const parseValueSurrealDB = (value: unknown, ct?: string): any => {
         }
         return `<datetime>"${value}"`; //let surrealDB try to do the conversion
       case 'FLEX': {
-        // array elements go throw the parsing
-        const parsedVal = isArray(value) ? value.map((v) => parseFlexValSurrealDB(v)) : parseFlexValSurrealDB(value);
-        return `${isArray(parsedVal) ? parsedVal.map((v) => v) : parsedVal}`;
+        return parseFlexValSurrealDB(value);
       }
       default:
         throw new Error(`Unsupported data field type ${ct}.`);

src/stateMachine/mutation/bql/enrich.ts

@@ -5,7 +5,7 @@ import { traverse } from 'object-traversal';
 import { isArray, isObject } from 'radash';
 import { getCurrentFields, getCurrentSchema, getFieldSchema } from '../../../helpers';
 import type { BormConfig, BQLMutationBlock, EnrichedBormSchema, EnrichedBQLMutationBlock } from '../../../types';
-import { SharedMetadata } from '../../../types/symbols';
+import { FlexDataValue, SharedMetadata } from '../../../types/symbols';
 import { enrichFilter } from '../../query/bql/enrich';
 import { computeFields } from './enrichSteps/computeFields';
 import { enrichChildren } from './enrichSteps/enrichChildren';
@@ -71,6 +71,11 @@ export const enrichBQLMutation = (
           return;
         }
 
+        if (FlexDataValue in value) {
+          //plain data objects in FLEX ref fields, not mutation nodes
+          return;
+        }
+
         if ('$root' in value) {
           // This is hte $root object, we will split the real root if needed in this iteration
         } else if (!('$thing' in value || '$entity' in value || '$relation' in value)) {

src/stateMachine/mutation/bql/enrichSteps/enrichChildren.ts

@@ -8,11 +8,21 @@ import type {
   EnrichedRefField,
   EnrichedRoleField,
 } from '../../../../types';
-import { EdgeSchema, SharedMetadata } from '../../../../types/symbols';
+import { EdgeSchema, FlexDataValue, SharedMetadata } from '../../../../types/symbols';
 import { get$bzId } from '../shared/get$bzId';
 import { getOp } from '../shared/getOp';
 import { getOppositePlayers } from '../shared/getOppositePlayers';
 
+const markFlexDataValues = (value: unknown): unknown => {
+  if (isArray(value)) {
+    return value.map(markFlexDataValues);
+  }
+  if (isObject(value)) {
+    return { ...(value as Record<string, unknown>), [FlexDataValue]: true };
+  }
+  return value;
+};
+
 export const enrichChildren = (
   node: BQLMutationBlock,
   field: string,
@@ -32,12 +42,21 @@ export const enrichChildren = (
 
       if (!isObject(subNode)) {
         if (refSchema.contentType === 'FLEX') {
+          if (isArray(subNode)) {
+            // Wrap in array to prevent flatMap from flattening the inner array,
+            // and recursively mark nested objects with FlexDataValue so the
+            // traverser in enrich.ts skips them.
+            return [markFlexDataValues(subNode)];
+          }
           return subNode;
         }
         throw new Error(`[Wrong format] The refField ${field} must receive an object`);
       }
 
       if (!subNode.$thing) {
+        if (refSchema.contentType === 'FLEX') {
+          return { ...subNode, [FlexDataValue]: true };
+        }
         throw new Error('[Wrong format] The field $thing is required in refFields');
       }
       return { ...subNode, $op, $bzId };

src/stateMachine/mutation/surql/build.ts

@@ -317,7 +317,19 @@ export const buildSURQLMutation = async (flat: FlatBqlMutation, schema: Enriched
       if (contentType === 'FLEX') {
         //todo: card one check len 1
         //todo: add/remove etc
-        return `${rf} = ${cardinality === 'ONE' ? `array::flatten([${block[rf]}])[0]` : `array::flatten([${block[rf]}])`}`;
+        if (cardinality === 'ONE') {
+          return `${rf} = array::flatten([${block[rf]}])[0]`;
+        }
+        // For MANY: flatten only variable references (entity matches) individually,
+        // keeping data values (including nested arrays/objects) as-is.
+        const elements = isArray(block[rf]) ? block[rf] : [block[rf]];
+        const processedElements = elements.map((el: unknown) => {
+          if (typeof el === 'string' && (el as string).startsWith('$')) {
+            return `array::flatten([${el}])[0]`;
+          }
+          return el;
+        });
+        return `${rf} = [${processedElements.join(', ')}]`;
       }
 
       throw new Error(`Unsupported contentType ${contentType}`);

src/types/symbols/index.ts

@@ -21,6 +21,9 @@ export const FieldSchema = Symbol.for('fieldSchema');
 /// Shared schema metadata
 export const SharedMetadata = Symbol.for('sharedMetadata');
 
+/// Marks plain objects stored as data values in FLEX ref fields
+export const FlexDataValue = Symbol.for('flexDataValue');
+
 /// SurrealDB schema metadata
 export const SuqlMetadata = Symbol.for('suqlMetadata');
 

tests/unit/mutations/refFields.ts

@@ -1135,4 +1135,78 @@ export const testRefFieldsMutations = createTest('Mutation: RefFields', (ctx) =>
       flexReferences: ['hello ? yes : no', 'User:abc:xyz', 'things it can do: jumping', 'User: hey', 'User:hey '],
     });
   });
+
+  it('fl8:[flex, object] Should accept objects in flexReferences', async () => {
+    const flexWithObject = {
+      id: 'fl8-flex-with-object',
+      flexReferences: [{ msg: 'Hello, world!' }],
+    };
+    await ctx.mutate(
+      [
+        {
+          ...flexWithObject,
+          $thing: 'FlexRefRel',
+          // We need to link something when creating a relation to avoid "[Wrong format] Can't create a relation without any player".
+          space: { id: 'fl8-space', name: 'fl8-space' },
+        },
+      ],
+      { noMetadata: true },
+    );
+
+    const res = await ctx.query(
+      {
+        $relation: 'FlexRefRel',
+        $id: 'fl8-flex-with-object',
+        $fields: ['id', 'flexReferences'],
+      },
+      { noMetadata: true },
+    );
+
+    //clean
+    await ctx.mutate({
+      $thing: 'FlexRefRel',
+      $op: 'delete',
+      $id: 'fl8-flex-with-object',
+      space: { $op: 'delete' },
+    });
+
+    expect(res).toEqual(flexWithObject);
+  });
+
+  it('fl9:[flex, object] Should accept an array of objects in flexReferences', async () => {
+    const flexWithObject = {
+      id: 'fl8-flex-with-object',
+      flexReferences: [[{ msg: 'Hello, world!' }]],
+    };
+    await ctx.mutate(
+      [
+        {
+          ...flexWithObject,
+          $thing: 'FlexRefRel',
+          // We need to link something when creating a relation to avoid "[Wrong format] Can't create a relation without any player".
+          space: { id: 'fl8-space', name: 'fl8-space' },
+        },
+      ],
+      { noMetadata: true },
+    );
+
+    const res = await ctx.query(
+      {
+        $relation: 'FlexRefRel',
+        $id: 'fl8-flex-with-object',
+        $fields: ['id', 'flexReferences'],
+      },
+      { noMetadata: true },
+    );
+
+    //clean
+    await ctx.mutate({
+      $thing: 'FlexRefRel',
+      $op: 'delete',
+      $id: 'fl8-flex-with-object',
+      space: { $op: 'delete' },
+    });
+
+    expect(res).toEqual(flexWithObject);
+  });
 });