Fix populate() for array fields with ref on items (#8324)

* Fix populate() for array fields with ref on items instead of on the array

RxDocument.populate() threw DOC6 for array fields when `ref` was defined
on `items` instead of on the array field itself, even though
createRxSchema accepts both patterns. Now populate() also checks
items.ref as a fallback for array-type schema fields.

https://claude.ai/code/session_012UknZ1m9tWSKkdi8nmWcqJ

* Move changelog entry to orga/changelog/ per project convention

The project uses individual files in orga/changelog/ instead of direct
edits to CHANGELOG.md, to avoid merge conflicts across PRs.

https://claude.ai/code/session_012UknZ1m9tWSKkdi8nmWcqJ

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: pubkey

orga/changelog/fix-populate-array-items-ref.md

@@ -0,0 +1 @@
+- FIX `RxDocument.populate()` throwing `DOC6` for array fields when `ref` is defined on `items` instead of on the array field itself, even though `createRxSchema` accepts both patterns

src/rx-document.ts

@@ -198,17 +198,22 @@ export const basePrototype = {
                 path
             });
         }
-        if (!schemaObj.ref) {
+        const ref = schemaObj.ref
+            ? schemaObj.ref
+            : (schemaObj.type === 'array' && schemaObj.items && (schemaObj.items as any).ref
+                ? (schemaObj.items as any).ref
+                : undefined);
+        if (!ref) {
             throw newRxError('DOC6', {
                 path,
                 schemaObj
             });
         }
 
-        const refCollection: RxCollection = this.collection.database.collections[schemaObj.ref];
+        const refCollection: RxCollection = this.collection.database.collections[ref];
         if (!refCollection) {
             throw newRxError('DOC7', {
-                ref: schemaObj.ref,
+                ref,
                 path,
                 schemaObj
             });

test/unit/population.test.ts

@@ -416,6 +416,63 @@ describeParallel('population.test.js', () => {
                 'populated array order for docB must match its ref id order'
             );
 
+            db.close();
+        });
+        it('populate array when ref is defined on items instead of on the array field', async () => {
+            const db = await createRxDatabase({
+                name: randomToken(10),
+                storage: config.storage.getStorage(),
+            });
+            const cols = await db.addCollections({
+                human: {
+                    schema: {
+                        version: 0,
+                        primaryKey: 'name',
+                        type: 'object',
+                        properties: {
+                            name: {
+                                type: 'string',
+                                maxLength: 100
+                            },
+                            friends: {
+                                type: 'array',
+                                items: {
+                                    ref: 'human',
+                                    type: 'string'
+                                }
+                            }
+                        }
+                    }
+                }
+            });
+            const col = cols.human;
+
+            const friendNames = ['alice', 'bob', 'charlie'];
+            await Promise.all(
+                friendNames.map(name => col.insert({ name, friends: [] }))
+            );
+            await col.insert({
+                name: 'protagonist',
+                friends: friendNames
+            });
+
+            const doc = await col.findOne('protagonist').exec(true);
+
+            // populate() must work when 'ref' is on items
+            const friendDocs = await doc.populate('friends');
+            assert.ok(Array.isArray(friendDocs));
+            assert.strictEqual(friendDocs.length, 3);
+            friendDocs.forEach((friend: any) => {
+                assert.ok(isRxDocument(friend));
+            });
+            const populatedNames = friendDocs.map((d: any) => d.name);
+            assert.deepStrictEqual(populatedNames, friendNames);
+
+            // pseudo-proxy _ getter must also work
+            const friendDocs2 = await (doc as any).friends_;
+            assert.ok(Array.isArray(friendDocs2));
+            assert.strictEqual(friendDocs2.length, 3);
+
             db.close();
         });
     });