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

package/.releaserc

@@ -1,6 +1,6 @@
 {
     "branches": [
-      "master", {"name":"PA-1117", "channel":"prerelease", "prerelease":"pa-1117"}
+      "master"
     ],
     "plugins": [
         "@semantic-release/release-notes-generator",

package/README.md

@@ -54,6 +54,26 @@ const [
     mergeWithFallback: true
   });
 
+// Query a multiple-entry content type by one or more fields.
+const shippingForms = await Stack.getMultiEntriesByFields(
+  'shipping_address_form',
+  {
+    country_code: 'US',
+    locale: 'en-us'
+  },
+  true
+);
+
+// Convenience wrapper when you only expect one result.
+const shippingForm = await Stack.getMultiEntryByFields(
+  'shipping_address_form',
+  {
+    country_code: 'US',
+    locale: 'en-us'
+  },
+  true
+);
+
 // We could possibly add functionality to return the list of regions markets and languages in a single object structure
 ```
 

package/__tests__/api.spec.js

@@ -16,6 +16,7 @@ const mockPromiseResult = jest.fn();
 const mockSinglePromiseResult = jest.fn();
 const mockStack = jest.fn();
 const mockContainedIn = jest.fn();
+const mockWhere = jest.fn();
 const mockIncludeReference = jest.fn();
 const mockFetch = jest.fn();
 
@@ -55,6 +56,7 @@ beforeEach(() => {
       })
     })),
     containedIn: mockContainedIn,
+    where: mockWhere,
     includeReference: mockIncludeReference,
     toJSON: jest.fn(() => ({
       find: mockPromiseResult
@@ -62,48 +64,123 @@ beforeEach(() => {
   };
 
   mockContainedIn.mockImplementation(() => mockQuery);
+  mockWhere.mockImplementation(() => mockQuery);
   mockIncludeReference.mockImplementation(() => mockQuery);
   mockStack.mockImplementation(() => ({
-    ContentType: () => ({
+    ContentType: (contentType) => ({
       Query: () => mockQuery,
-      fetch: mockFetch
+      fetch: () => mockFetch(contentType)
     })
   }));
 
-  mockFetch.mockResolvedValue({
-    content_type: {
-      schema: [
-        {
-          uid: 'countries',
-          data_type: 'reference'
-        },
-        {
-          uid: 'details',
-          data_type: 'group',
+  mockFetch.mockImplementation((contentType) => {
+    const schemas = {
+      shipping_address_form: {
+        content_type: {
           schema: [
             {
-              uid: 'address_form',
-              data_type: 'reference'
-            }
-          ]
-        },
-        {
-          uid: 'promo_blocks',
-          data_type: 'blocks',
-          blocks: [
+              uid: 'countries',
+              data_type: 'reference',
+              reference_to: 'market'
+            },
             {
-              uid: 'hero',
+              uid: 'details',
+              data_type: 'group',
               schema: [
                 {
-                  uid: 'banner',
-                  data_type: 'reference'
+                  uid: 'address_form',
+                  data_type: 'reference',
+                  reference_to: 'address_form'
+                }
+              ]
+            },
+            {
+              uid: 'promo_blocks',
+              data_type: 'blocks',
+              blocks: [
+                {
+                  uid: 'hero',
+                  schema: [
+                    {
+                      uid: 'banner',
+                      data_type: 'reference',
+                      reference_to: 'banner'
+                    }
+                  ]
                 }
               ]
             }
           ]
         }
-      ]
-    }
+      },
+      address_form: {
+        content_type: {
+          schema: [
+            {
+              uid: 'address_elements',
+              data_type: 'reference',
+              reference_to: 'address_form_field'
+            }
+          ]
+        }
+      },
+      market: {
+        content_type: {
+          schema: []
+        }
+      },
+      banner: {
+        content_type: {
+          schema: []
+        }
+      },
+      address_form_field: {
+        content_type: {
+          schema: [
+            {
+              uid: 'field_config',
+              data_type: 'reference',
+              reference_to: 'field_config'
+            }
+          ]
+        }
+      },
+      field_config: {
+        content_type: {
+          schema: [
+            {
+              uid: 'validation_rule',
+              data_type: 'reference',
+              reference_to: 'validation_rule'
+            }
+          ]
+        }
+      },
+      validation_rule: {
+        content_type: {
+          schema: [
+            {
+              uid: 'too_deep_reference',
+              data_type: 'reference',
+              reference_to: 'too_deep_reference'
+            }
+          ]
+        }
+      },
+      too_deep_reference: {
+        content_type: {
+          schema: [
+            {
+              uid: 'should_not_be_included',
+              data_type: 'reference',
+              reference_to: 'market'
+            }
+          ]
+        }
+      }
+    };
+
+    return Promise.resolve(schemas[contentType] || {content_type: {schema: []}});
   });
 
   jest.mock("contentstack", () => ({Stack: mockStack}));
@@ -113,6 +190,7 @@ afterEach(() => {
   mockSinglePromiseResult.mockReset();
   mockPromiseResult.mockReset();
   mockContainedIn.mockReset();
+  mockWhere.mockReset();
   mockIncludeReference.mockReset();
   mockFetch.mockReset();
   //jest.resetAllMocks(); don't reset the mockStack function
@@ -222,10 +300,13 @@ describe("ContentstackApi", () => {
     const {getStack} = require('../src/api');
     const Stack = getStack('dev');
     await Stack.getMultiEntries('shipping_address_form', true, ['United States']);
-    expect(mockFetch).toHaveBeenCalledTimes(1);
+    expect(mockFetch).toHaveBeenCalledTimes(6);
     expect(mockIncludeReference).toHaveBeenCalledWith([
       'countries',
       'details.address_form',
+      'details.address_form.address_elements',
+      'details.address_form.address_elements.field_config',
+      'details.address_form.address_elements.field_config.validation_rule',
       'promo_blocks.hero.banner'
     ]);
   });
@@ -236,16 +317,104 @@ describe("ContentstackApi", () => {
     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(mockFetch).toHaveBeenCalledTimes(6);
     expect(mockIncludeReference).toHaveBeenNthCalledWith(1, [
       'countries',
       'details.address_form',
+      'details.address_form.address_elements',
+      'details.address_form.address_elements.field_config',
+      'details.address_form.address_elements.field_config.validation_rule',
       'promo_blocks.hero.banner'
     ]);
     expect(mockIncludeReference).toHaveBeenNthCalledWith(2, [
       'countries',
       'details.address_form',
+      'details.address_form.address_elements',
+      'details.address_form.address_elements.field_config',
+      'details.address_form.address_elements.field_config.validation_rule',
       'promo_blocks.hero.banner'
     ]);
   });
+
+  test('getMultiEntries limits automatic reference traversal to four levels deep', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('stage');
+    await Stack.getMultiEntries('shipping_address_form', true, ['United States']);
+    expect(mockIncludeReference).toHaveBeenCalledWith([
+      'countries',
+      'details.address_form',
+      'details.address_form.address_elements',
+      'details.address_form.address_elements.field_config',
+      'details.address_form.address_elements.field_config.validation_rule',
+      'promo_blocks.hero.banner'
+    ]);
+    expect(mockIncludeReference).not.toHaveBeenCalledWith(expect.arrayContaining([
+      'details.address_form.address_elements.field_config.validation_rule.too_deep_reference',
+      'details.address_form.address_elements.field_config.validation_rule.too_deep_reference.should_not_be_included'
+    ]));
+  });
+
+  test('getMultiEntriesByFields applies where filters for scalar values', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('prod');
+    await Stack.getMultiEntriesByFields('market', {
+      country_code: 'US',
+      locale: 'en-us'
+    });
+    expect(mockWhere).toHaveBeenNthCalledWith(1, 'country_code', 'US');
+    expect(mockWhere).toHaveBeenNthCalledWith(2, 'locale', 'en-us');
+    expect(mockContainedIn).not.toHaveBeenCalled();
+  });
+
+  test('getMultiEntriesByFields applies containedIn for array values', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('dev');
+    await Stack.getMultiEntriesByFields('market', {
+      title: ['United States', 'Canada'],
+      locale: 'en-us'
+    });
+    expect(mockContainedIn).toHaveBeenCalledWith('title', ['United States', 'Canada']);
+    expect(mockWhere).toHaveBeenCalledWith('locale', 'en-us');
+  });
+
+  test('getMultiEntriesByFields resolves include refs when requested', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[{title: 'United States'}]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('stage');
+    await Stack.getMultiEntriesByFields('shipping_address_form', {
+      country_code: 'US',
+      locale: 'en-us'
+    }, true);
+    expect(mockIncludeReference).toHaveBeenCalledWith([
+      'countries',
+      'details.address_form',
+      'details.address_form.address_elements',
+      'details.address_form.address_elements.field_config',
+      'details.address_form.address_elements.field_config.validation_rule',
+      'promo_blocks.hero.banner'
+    ]);
+  });
+
+  test('getMultiEntriesByFields throws when fields are missing', async () => {
+    const {getStack} = require('../src/api');
+    const Stack = getStack('dev');
+    await expect(Stack.getMultiEntriesByFields('market')).rejects.toStrictEqual(
+      new Error('Call to getMultiEntriesByFields: fields are required')
+    );
+  });
+
+  test('getMultiEntryByFields returns the first matching entry', async () => {
+    mockPromiseResult.mockResolvedValueOnce([[
+      {title: 'United States'},
+      {title: 'Canada'}
+    ]]);
+    const {getStack} = require('../src/api');
+    const Stack = getStack('test');
+    await expect(Stack.getMultiEntryByFields('market', {
+      locale: 'en-us'
+    })).resolves.toStrictEqual({title: 'United States'});
+  });
 });

package/docs/CHANGELOG.md

@@ -1 +1 @@
-# [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)
+# [2.1.0](https://code.tls.nuskin.io/ns-am/utility/npm/contentstack-lib/compare/v2.0.2...v2.1.0) (2026-06-26)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuskin/contentstack-lib",
-  "version": "2.1.0-pa-1117.11",
+  "version": "2.1.0",
   "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

@@ -9,6 +9,8 @@ const {contentstack: prodEnvConfig} = require(`../config/prod.json`);
 let env = null;
 let Stack = null;
 const referenceFieldCache = new Map();
+const contentTypeSchemaCache = new Map();
+const MAX_REFERENCE_DEPTH = 4;
 
 const COMMON_LANGUAGES = {
   'da': 'da-dk',
@@ -174,33 +176,80 @@ 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) => {
+async function _getContentTypeSchema(contentType) {
+  if (contentTypeSchemaCache.has(contentType)) {
+    return contentTypeSchemaCache.get(contentType);
+  }
+
+  const contentTypeSchema = await Stack.ContentType(contentType).fetch();
+  const schema = contentTypeSchema.content_type.schema || [];
+  contentTypeSchemaCache.set(contentType, schema);
+  return schema;
+}
+
+async function _collectReferenceFieldPathsForSchema(schema = [], parentPath = '', visited = new Set(), depth = 0) {
+  const allPaths = [];
+
+  for (const field of schema) {
     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
-    ];
-  });
+
+    if (Array.isArray(field.schema)) {
+      const nestedSchemaPaths = await _collectReferenceFieldPathsForSchema(field.schema, currentPath, visited, depth);
+      allPaths.push(...nestedSchemaPaths);
+    }
+
+    if (field.data_type === 'blocks' && Array.isArray(field.blocks)) {
+      for (const block of field.blocks) {
+        if (Array.isArray(block.schema)) {
+          const blockPaths = await _collectReferenceFieldPathsForSchema(
+            block.schema,
+            `${currentPath}.${block.uid}`,
+            visited,
+            depth
+          );
+          allPaths.push(...blockPaths);
+        }
+      }
+    }
+
+    if (field.data_type === 'reference') {
+      const currentDepth = depth + 1;
+      if (currentDepth > MAX_REFERENCE_DEPTH) {
+        continue;
+      }
+      allPaths.push(currentPath);
+      const referenceTargets = Array.isArray(field.reference_to) ?
+        field.reference_to :
+        field.reference_to ? [field.reference_to] : [];
+
+      if (currentDepth >= MAX_REFERENCE_DEPTH) {
+        continue;
+      }
+
+      for (const referencedContentType of referenceTargets) {
+        const nestedReferencePaths = await _collectReferenceFieldPathsForContentType(
+          referencedContentType,
+          currentPath,
+          visited,
+          currentDepth
+        );
+        allPaths.push(...nestedReferencePaths);
+      }
+    }
+  }
+
+  return [...new Set(allPaths)];
+}
+
+async function _collectReferenceFieldPathsForContentType(contentType, parentPath = '', visited = new Set(), depth = 0) {
+  const visitKey = `${contentType}|${parentPath}|${depth}`;
+  if (visited.has(visitKey)) {
+    return [];
+  }
+  visited.add(visitKey);
+
+  const schema = await _getContentTypeSchema(contentType);
+  return _collectReferenceFieldPathsForSchema(schema, parentPath, visited, depth);
 }
 
 /**
@@ -231,12 +280,26 @@ async function _resolveIncludeRefs(contentType, includeRefs) {
     return referenceFieldCache.get(contentType);
   }
 
-  const contentTypeSchema = await Stack.ContentType(contentType).fetch();
-  const referenceFields = _collectReferenceFieldPaths(contentTypeSchema.content_type.schema);
+  const referenceFields = await _collectReferenceFieldPathsForContentType(contentType);
   referenceFieldCache.set(contentType, referenceFields);
   return referenceFields;
 }
 
+/**
+ * Apply field filters to a query. Scalar values use where(), arrays use containedIn().
+ * @param {Object} query
+ * @param {Object<string, string|string[]>} fields
+ * @return {Object}
+ * @private
+ */
+function _applyFieldFilters(query, fields) {
+  return Object.entries(fields).reduce((currentQuery, [field, value]) => {
+    return Array.isArray(value) ?
+      currentQuery.containedIn(field, value) :
+      currentQuery.where(field, value);
+  }, query);
+}
+
 /**
  * Gets all the specified entries for a multiple content type
  * @param {string} contentType
@@ -264,6 +327,51 @@ const getMultiEntries = async (contentType, includeRefs, values) => {
   }
 };
 
+/**
+ * Gets entries for a multiple content type filtered by one or more fields.
+ * @param {string} contentType
+ * @param {Object<string, string|string[]>} fields
+ * @param {boolean|string|string[]=} includeRefs
+ * @return {Promise<Object[]>}
+ */
+const getMultiEntriesByFields = async (contentType, fields, includeRefs) => {
+  if (!fields || !Object.keys(fields).length) {
+    throw new Error('Call to getMultiEntriesByFields: fields are required');
+  }
+
+  try {
+    const resolvedIncludeRefs = await _resolveIncludeRefs(contentType, includeRefs);
+    let query = _applyFieldFilters(
+      Stack
+        .ContentType(contentType)
+        .Query(),
+      fields
+    );
+
+    if (resolvedIncludeRefs.length) {
+      query = query.includeReference(resolvedIncludeRefs);
+    }
+
+    const [results] = await query.toJSON().find();
+    return results;
+  } catch (err) {
+    console.error(err);
+    return [];
+  }
+};
+
+/**
+ * Gets the first matching entry for a multiple content type filtered by fields.
+ * @param {string} contentType
+ * @param {Object<string, string|string[]>} fields
+ * @param {boolean|string|string[]=} includeRefs
+ * @return {Promise<Object|undefined>}
+ */
+const getMultiEntryByFields = async (contentType, fields, includeRefs) => {
+  const results = await getMultiEntriesByFields(contentType, fields, includeRefs);
+  return results[0];
+};
+
 /**
  * Returns contentstack Stack object initialized with the api key, deliveryToken, and extended with custom functionality
  * @param {'dev' | 'test' | 'stage' | 'prod'} envrnmnt
@@ -284,12 +392,15 @@ function getStack(envrnmnt) {
 
   env = envrnmnt;
   referenceFieldCache.clear();
+  contentTypeSchemaCache.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;
   Stack.getMultiEntries = getMultiEntries;
+  Stack.getMultiEntriesByFields = getMultiEntriesByFields;
+  Stack.getMultiEntryByFields = getMultiEntryByFields;
 
   return Stack;
 }