[Bug]: Inconsistent Response Format for Custom Links When Single Item Is Present

[maselious]

Package.json file

{
  "name": "medusa-starter-default",
  "version": "0.0.1",
  "description": "A starter for Medusa projects.",
  "author": "Medusa (https://medusajs.com)",
  "license": "MIT",
  "keywords": [
    "sqlite",
    "postgres",
    "typescript",
    "ecommerce",
    "headless",
    "medusa"
  ],
  "scripts": {
    "build": "medusa build",
    "seed": "medusa exec ./src/scripts/seed.ts",
    "start": "medusa start",
    "dev": "medusa develop",
    "prod:start": "medusa db:migrate && yarn start",
    "test:integration:http": "TEST_TYPE=integration:http NODE_OPTIONS=--experimental-vm-modules jest --silent=false --runInBand --forceExit",
    "test:integration:modules": "TEST_TYPE=integration:modules NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
    "test:unit": "TEST_TYPE=unit NODE_OPTIONS=--experimental-vm-modules jest --silent --runInBand --forceExit",
    "format": "prettier --write ."
  },
  "dependencies": {
    "@medusajs/admin-sdk": "^2.1.0",
    "@medusajs/cli": "^2.1.0",
    "@medusajs/framework": "^2.1.0",
    "@medusajs/icons": "^2.1.0",
    "@medusajs/js-sdk": "^2.1.0",
    "@medusajs/medusa": "^2.1.0",
    "@mikro-orm/core": "5.9.7",
    "@mikro-orm/knex": "5.9.7",
    "@mikro-orm/migrations": "5.9.7",
    "@mikro-orm/postgresql": "5.9.7",
    "@notionhq/client": "^2.2.15",
    "@tanstack/react-query": "^5.62.1",
    "awilix": "^8.0.1",
    "lodash": "^4.17.21",
    "pg": "^8.13.0",
    "react-router-dom": "^7.0.1"
  },
  "devDependencies": {
    "@medusajs/test-utils": "^2.1.0",
    "@medusajs/types": "^2.1.0",
    "@mikro-orm/cli": "5.9.7",
    "@swc/core": "1.5.7",
    "@swc/jest": "^0.2.36",
    "@types/jest": "^29.5.13",
    "@types/lodash": "^4",
    "@types/node": "^20.0.0",
    "@types/react": "^18.3.2",
    "@types/react-dom": "^18.2.25",
    "jest": "^29.7.0",
    "prettier": "^3.4.1",
    "prop-types": "^15.8.1",
    "react": "^18.2.0",
    "react-dom": "^18.2.0",
    "ts-node": "^10.9.2",
    "typescript": "^5.6.2",
    "vite": "^5.2.11"
  },
  "engines": {
    "node": ">=20"
  },
  "packageManager": "yarn@4.5.1"
}

Node.js version

v20.9.0

Database and its version

Postgre SQL 17

Operating system name and version

Mac Os 15.1.1 (24B91)

Browser name

Arc

What happended?

When creating a custom link using defineLink, if there is only one linked item (e.g., a single image), the response returns an object instead of an array. However, when there are multiple items, the response correctly returns an array. This inconsistency complicates data handling on the client side.

Link Defination

export default defineLink(
  ProductModule.linkable.productVariant,
  VariantImages.linkable.variantImage,
  {
    database: {
      table: 'variant_image_links',
    },
    isList: true,
  }
);

Expected behavior

The response should consistently return an array, even when there is only one linked item, to ensure uniform data handling.

Actual behavior

For a single linked image, the response is an object:

{
    "id": "variant_01JEDTFWSHE5BXF3DDTB9M5NGS",
    "variant_image": {
        "url": "https://...T0RJT5XRND571PR8P2.png",
        "id": "vimg_01JEDTG77R093VXC1G22EFWZCY"
    }
}

For multiple linked images, the response is an array:

{
    "id": "variant_01JEDTFWSGABGNYKH28ZE52QED",
    "variant_image": [
        {
            "url": "https://...EDTG9WDFH1QAXN6CJFCKYAA.png",
            "id": "vimg_01JEDTGBNA36P2VNXNZGBD9DX5"
        },
        {
            "url": "https://...WD24WV13DDMNX1SC31.png",
            "id": "vimg_01JEDTGBNBDV8X6WE9859XT8T9"
        },
        {
            "url": "....DTG9WERZ7BBWAANKWZYR25.png",
            "id": "vimg_01JEDTGBNBRX7XZX6MX43H4XS2"
        }
    ]
}

Link to reproduction repo

private repo

[sradevski]

@maselious how are you querying it? I agree that this isn't expected

[maselious]

@sradevski
Native Admin API, no overrides in product related api or workflows

Middlewares

export default defineMiddlewares({
    routes: [
        {
            method: ['POST'],
            matcher: '/admin/products/sync',
            middlewares: [validateAndTransformBody(syncProductsSchema)]
        },
        {
            method: ['POST'],
            matcher: '/store/carts/:id',
            additionalDataValidator: {
                preferences: cartAddDataPreferencesSchema
            }
        }
    ]
})

GET /admin/products

fields=variants.variant_image.url
limit=2

{
    "products": [
        {
            "id": "prod_01JEE2CNFZ4WZ3NBPPS26FX56D",
            "variants": [
                {
                    "id": "variant_01JEE2CNH4VNS3XXPYMY0WD3N0",
                    "variant_image": {
                        "url": "...0007-01JEE2D42FZ4H3KJD9R49Z2AWH.png",
                        "id": "vimg_01JEE2D629MCE9611ZVA03RNES"
                    }
                },
                {
                    "id": "variant_01JEE2CNH3TWHN5EBFXS4F3JPG",
                    "variant_image": [
                        {
                            "url": "...XRTHD1DR6AV5Z8WJ.png",
                            "id": "vimg_01JEE2D9JMBEQCG4YFVX8DDFWS"
                        },
                        {
                            "url": "...27BNNCB97.png",
                            "id": "vimg_01JEE2D9JNPVA9WJ19MPPHABGZ"
                        },
                        {
                            "url": "...8N8PWHNVY.png",
                            "id": "vimg_01JEE2D9JNR44YPXKA3C11SM1Z"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH38N58A81H1SS99V8X",
                    "variant_image": [
                        {
                            "url": "...9YFC5PQ8P.png",
                            "id": "vimg_01JEE2D95WE9428WRMK8T3JC57"
                        },
                        {
                            "url": "...JDSVV27HT.png",
                            "id": "vimg_01JEE2D95XQ8848AHN0QDCJFJY"
                        },
                        {
                            "url": "...48PFG9BZQ.png",
                            "id": "vimg_01JEE2D95X20EBNKPVAMSVN41M"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH36QXEDCWDHJHD46W6",
                    "variant_image": [
                        {
                            "url": "...K7DM59YF51.png",
                            "id": "vimg_01JEE2D2M7WPAK43Y4CWSTA1HM"
                        },
                        {
                            "url": "...7FZT65GVB154KBFNV.png",
                            "id": "vimg_01JEE2D2M74S19DAXS6BS2576B"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH32NWXKYDVR26TFSK7",
                    "variant_image": [
                        {
                            "url": "...Q0895WXTSV22YZY.png",
                            "id": "vimg_01JEE2D3R0W99WW4BDF9RYHG61"
                        },
                        {
                            "url": "...CNYM489NA9ES7879D.png",
                            "id": "vimg_01JEE2D3R04KNYWGWEVWVHXEA2"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH4BXSREW72F9QD6SX0",
                    "variant_image": [
                        {
                            "url": "...W4XCJYG4D2M3GK463.png",
                            "id": "vimg_01JEE2D63FA0DDKV60S42GCZ36"
                        },
                        {
                            "url": "...M588MXZAKZ2P97Y.png",
                            "id": "vimg_01JEE2D63FFAGXMX8PJCFZXVQA"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH33KCHZQCGVF5466S6",
                    "variant_image": [
                        {
                            "url": "...Q3FW75YHCF5D8Y.png",
                            "id": "vimg_01JEE2D9PQ0JX2D497RDXB6XDG"
                        },
                        {
                            "url": "...EM9MW9NR13Z120.png",
                            "id": "vimg_01JEE2D9PRFWAVAZ0Q9JSHNDEF"
                        },
                        {
                            "url": "...6YMEPP66JC835.png",
                            "id": "vimg_01JEE2D9PR7J9G8KPCV526K7WM"
                        }
                    ]
                }
            ]
        },
        {
            "id": "prod_01JEE2CNFZK79V4FN9MZBC36G0",
            "variants": [
                {
                    "id": "variant_01JEE2CNH3B0G1PB9BJ6JTQM8Q",
                    "variant_image": [
                        {
                            "url": "...CEN5M4XZ429EW.png",
                            "id": "vimg_01JEE2DA2C8W8GENWJD47BVS4K"
                        },
                        {
                            "url": "...ZEXQ789JP07GQB.png",
                            "id": "vimg_01JEE2DA2C8AQX7YFM0TDFVW5B"
                        },
                        {
                            "url": "...RC5NKBKAFMTMN.png",
                            "id": "vimg_01JEE2DA2CNDG7FZ172XHC2NSX"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH30Y3H5FN5X49VQ2JV",
                    "variant_image": [
                        {
                            "url": "...YDT0570N4NC3MR5.png",
                            "id": "vimg_01JEE2D9YNTC5HSD0Y8H5JFJER"
                        },
                        {
                            "url": "...CB45HMMM88BW.png",
                            "id": "vimg_01JEE2D9YPDHMJJW62DS95QMH8"
                        },
                        {
                            "url": "...2AAVZ72S5W9V.png",
                            "id": "vimg_01JEE2D9YP5AQSWJBYB1V3CKQD"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH3T7VMQ43JBJ4X4XYM",
                    "variant_image": [
                        {
                            "url": "...SC5388SVY9BFD.png",
                            "id": "vimg_01JEE2D62CSFG99FG86JH01HF9"
                        },
                        {
                            "url": "...AQ633DCF4DAPT0.png",
                            "id": "vimg_01JEE2D62CCB5SB30YSWTVJK2R"
                        },
                        {
                            "url": "...5VYSPVSG9AQ.png",
                            "id": "vimg_01JEE2D62DGS6T881QZQK3G58P"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH316Y8ZVH0MW68BPTN",
                    "variant_image": [
                        {
                            "url": "...X6TA46RPEM0EAPR.png",
                            "id": "vimg_01JEE2D8BB8N3JNNCBJZFF3K8P"
                        },
                        {
                            "url": "...M419PTZSXV2HZE3.png",
                            "id": "vimg_01JEE2D8BB49YSEPYHCR79N875"
                        },
                        {
                            "url": "...BHHKV07J9A6W014.png",
                            "id": "vimg_01JEE2D8BBHP5QGKXTP78NSEXR"
                        }
                    ]
                },
                {
                    "id": "variant_01JEE2CNH371BJ1JVC0A4J87PQ",
                    "variant_image": [
                        {
                            "url": "...TH7DDC9KTYHG347TG.png",
                            "id": "vimg_01JEE2DA563P8G3YY8VZD7KVZK"
                        },
                        {
                            "url": "...1EV8CD29VEFAHB2.png",
                            "id": "vimg_01JEE2DA5609EMQZ2NWTG8KQ1V"
                        },
                        {
                            "url": "...2ET66K89P6AYAGZ8.png",
                            "id": "vimg_01JEE2DA56JN49EWXC0221VTFJ"
                        }
                    ]
                }
            ]
        }
    ],
    "count": 2,
    "offset": 0,
    "limit": 2
}

[sradevski]

Ok thanks, we'll have a look at it!

[carlos-r-l-rodrigues]

Hi @maselious,
this is what you need:

export default defineLink(
  ProductModule.linkable.productVariant,
  {
    ...VariantImages.linkable.variantImage.id,
    isList: true,
  },
  {
    database: {
      table: 'variant_image_links',
    }
  }
);

[maselious]

Hi @maselious, this is what you need:

export default defineLink(
  ProductModule.linkable.productVariant,
  {
    ...VariantImages.linkable.variantImage.id,
    isList: true,
  },
  {
    database: {
      table: 'variant_image_links',
    }
  }
);

Perfect, thank you! Then there is another issue i would say: if the link is one-to-one, there should be an error while trying to assign an array or the relations should be overridden, isnt it?

I made it as written in the doc

export default defineLink(
    ProductModule.linkable.productVariant,
    {
        linkable: VariantImages.linkable.variantImage,
        isList: true
    },
    {
        database: {
            table: 'variant_image_links'
        }
    }
)