@nuskin/contentstack-lib 2.1.0-pa-1117.10 → 2.1.0-pa-1117.11

package/__tests__/api.spec.js

@@ -15,6 +15,9 @@ const {contentstack: prodEnvConfig} = require(`../config/prod.json`);
 const mockPromiseResult = jest.fn();
 const mockSinglePromiseResult = jest.fn();
 const mockStack = jest.fn();
+const mockContainedIn = jest.fn();
+const mockIncludeReference = jest.fn();
+const mockFetch = jest.fn();
 
 function getConfig(env) {
   let config = {};
@@ -42,34 +45,76 @@ function getConfig(env) {
 }
 
 beforeEach(() => {
-  mockStack.mockImplementation(() => ({
-    ContentType: () => ({
-      Query: () => ({
-        language: () => ({
-          includeFallback: () => ({
-            toJSON: () => ({
-              find: mockPromiseResult,
-              findOne: mockSinglePromiseResult
-            })
-          })
-        }),
-        containedIn: () => ({
-          includeReference: () => ({
-            toJSON: () => ({
-              find: mockPromiseResult
-            })
-          })
+  const mockQuery = {
+    language: jest.fn(() => ({
+      includeFallback: () => ({
+        toJSON: () => ({
+          find: mockPromiseResult,
+          findOne: mockSinglePromiseResult
         })
       })
+    })),
+    containedIn: mockContainedIn,
+    includeReference: mockIncludeReference,
+    toJSON: jest.fn(() => ({
+      find: mockPromiseResult
+    }))
+  };
+
+  mockContainedIn.mockImplementation(() => mockQuery);
+  mockIncludeReference.mockImplementation(() => mockQuery);
+  mockStack.mockImplementation(() => ({
+    ContentType: () => ({
+      Query: () => mockQuery,
+      fetch: mockFetch
     })
   }));
 
+  mockFetch.mockResolvedValue({
+    content_type: {
+      schema: [
+        {
+          uid: 'countries',
+          data_type: 'reference'
+        },
+        {
+          uid: 'details',
+          data_type: 'group',
+          schema: [
+            {
+              uid: 'address_form',
+              data_type: 'reference'
+            }
+          ]
+        },
+        {
+          uid: 'promo_blocks',
+          data_type: 'blocks',
+          blocks: [
+            {
+              uid: 'hero',
+              schema: [
+                {
+                  uid: 'banner',
+                  data_type: 'reference'
+                }
+              ]
+            }
+          ]
+        }
+      ]
+    }
+  });
+
   jest.mock("contentstack", () => ({Stack: mockStack}));
 });
 
 afterEach(() => {
   mockSinglePromiseResult.mockReset();
   mockPromiseResult.mockReset();
+  mockContainedIn.mockReset();
+  mockIncludeReference.mockReset();
+  mockFetch.mockReset();
   //jest.resetAllMocks(); don't reset the mockStack function
 });
 
@@ -78,7 +123,7 @@ const mockResults = () => {
   mockPromiseResult.mockResolvedValueOnce(checkoutAdrStrings);
   mockSinglePromiseResult.mockResolvedValueOnce(singleCheckoutAdrStrings);
   mockSinglePromiseResult.mockResolvedValueOnce(singleCheckoutCartStrings);
-}
+};
 
 describe("ContentstackApi", () => {
   test("getSingletonEntries", async () => {
@@ -152,4 +197,55 @@ describe("ContentstackApi", () => {
     await Stack.getSingletonEntries({contentTypeUIDs: ['checkout_adr_strings'], language: 'in'});
     expect(mockSinglePromiseResult).toHaveBeenCalled();
   });
+
+  test('getMultiEntries does not include references when includeRefs is false', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('dev');
+    await Stack.getMultiEntries('market', false, ['United States']);
+    expect(mockContainedIn).toHaveBeenCalledWith('title', ['United States']);
+    expect(mockIncludeReference).not.toHaveBeenCalled();
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  test('getMultiEntries includes explicit reference paths', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('dev');
+    await Stack.getMultiEntries('market', ['countries', 'address_form.address_elements'], ['United States']);
+    expect(mockIncludeReference).toHaveBeenCalledWith(['countries', 'address_form.address_elements']);
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+
+  test('getMultiEntries discovers reference paths from schema when includeRefs is true', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('dev');
+    await Stack.getMultiEntries('shipping_address_form', true, ['United States']);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockIncludeReference).toHaveBeenCalledWith([
+      'countries',
+      'details.address_form',
+      'promo_blocks.hero.banner'
+    ]);
+  });
+
+  test('getMultiEntries caches discovered reference paths per content type', async () => {
+    mockPromiseResult.mockResolvedValue([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('test');
+    await Stack.getMultiEntries('shipping_address_form', true, ['United States']);
+    await Stack.getMultiEntries('shipping_address_form', true, ['Canada']);
+    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockIncludeReference).toHaveBeenNthCalledWith(1, [
+      'countries',
+      'details.address_form',
+      'promo_blocks.hero.banner'
+    ]);
+    expect(mockIncludeReference).toHaveBeenNthCalledWith(2, [
+      'countries',
+      'details.address_form',
+      'promo_blocks.hero.banner'
+    ]);
+  });
 });

package/docs/CHANGELOG.md

@@ -1 +1 @@
-# [2.1.0-pa-1117.10](https://code.tls.nuskin.io/ns-am/utility/npm/contentstack-lib/compare/v2.1.0-pa-1117.9...v2.1.0-pa-1117.10) (2026-05-20)
+# [2.1.0-pa-1117.11](https://code.tls.nuskin.io/ns-am/utility/npm/contentstack-lib/compare/v2.1.0-pa-1117.10...v2.1.0-pa-1117.11) (2026-05-21)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuskin/contentstack-lib",
-  "version": "2.1.0-pa-1117.10",
+  "version": "2.1.0-pa-1117.11",
   "description": "This project contains configuration and api code to access Contentstack, to be shared between the backend (AWS Lambda) and frontend (Vue, etc).",
   "main": "src/index.js",
   "scripts": {

package/src/api.js

@@ -8,6 +8,7 @@ const {contentstack: prodEnvConfig} = require(`../config/prod.json`);
 
 let env = null;
 let Stack = null;
+const referenceFieldCache = new Map();
 
 const COMMON_LANGUAGES = {
   'da': 'da-dk',
@@ -173,6 +174,69 @@ async function getSingletonEntries(options) {
   }
 }
 
+/**
+ * Collect reference field paths recursively from a content type schema.
+ * @param {Object[]} schema
+ * @param {string=} parentPath
+ * @return {string[]}
+ * @private
+ */
+function _collectReferenceFieldPaths(schema = [], parentPath = '') {
+  return schema.flatMap((field) => {
+    const currentPath = parentPath ? `${parentPath}.${field.uid}` : field.uid;
+    const nestedSchemaPaths = Array.isArray(field.schema) ?
+      _collectReferenceFieldPaths(field.schema, currentPath) :
+      [];
+    const blockPaths = field.data_type === 'blocks' && Array.isArray(field.blocks) ?
+      field.blocks.flatMap((block) => {
+        return Array.isArray(block.schema) ?
+          _collectReferenceFieldPaths(block.schema, `${currentPath}.${block.uid}`) :
+          [];
+      }) :
+      [];
+
+    return [
+      ...(field.data_type === 'reference' ? [currentPath] : []),
+      ...nestedSchemaPaths,
+      ...blockPaths
+    ];
+  });
+}
+
+/**
+ * Resolve reference include paths from a boolean, string, or array input.
+ * @param {string} contentType
+ * @param {boolean|string|string[]} includeRefs
+ * @return {Promise<string[]>}
+ * @private
+ */
+async function _resolveIncludeRefs(contentType, includeRefs) {
+  if (!includeRefs) {
+    return [];
+  }
+
+  if (typeof includeRefs === 'string') {
+    return [includeRefs];
+  }
+
+  if (Array.isArray(includeRefs)) {
+    return includeRefs;
+  }
+
+  if (includeRefs !== true) {
+    return [];
+  }
+
+  if (referenceFieldCache.has(contentType)) {
+    return referenceFieldCache.get(contentType);
+  }
+
+  const contentTypeSchema = await Stack.ContentType(contentType).fetch();
+  const referenceFields = _collectReferenceFieldPaths(contentTypeSchema.content_type.schema);
+  referenceFieldCache.set(contentType, referenceFields);
+  return referenceFields;
+}
+
 /**
  * Gets all the specified entries for a multiple content type
  * @param {string} contentType
@@ -181,19 +245,24 @@ async function getSingletonEntries(options) {
  */
 const getMultiEntries = async (contentType, includeRefs, values) => {
   try {
-    const [results] = await Stack
+    const resolvedIncludeRefs = await _resolveIncludeRefs(contentType, includeRefs);
+
+    let query = Stack
       .ContentType(contentType)
       .Query()
-      .containedIn('title', values)
-      .includeReference(includeRefs)
-      .toJSON()
-      .find();
+      .containedIn('title', values);
+
+    if (resolvedIncludeRefs.length) {
+      query = query.includeReference(resolvedIncludeRefs);
+    }
+
+    const [results] = await query.toJSON().find();
 
     return results;
   } catch(err) {
     console.error(err);
   }
-}
+};
 
 /**
  * Returns contentstack Stack object initialized with the api key, deliveryToken, and extended with custom functionality
@@ -214,8 +283,9 @@ function getStack(envrnmnt) {
   }
 
   env = envrnmnt;
-  const {apiKey: api_key, deliveryToken: delivery_token, environment} = getConfig(env)
-  Stack = Contentstack.Stack({api_key, delivery_token, environment})
+  referenceFieldCache.clear();
+  const {apiKey: api_key, deliveryToken: delivery_token, environment} = getConfig(env);
+  Stack = Contentstack.Stack({api_key, delivery_token, environment});
 
   // extend the Stack with a custom function to get translations
   Stack.getSingletonEntries = getSingletonEntries;