Merge pull request #261 from contentstack/enh/dx-5408

Added variant utility

Author: sunil-lakshman

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Changelog
 
+## [1.9.0](https://github.com/contentstack/contentstack-utils-javascript/tree/v1.9.0)
+- Feat: Variant utilities `getVariantAliases` and `getVariantMetadataTags` to read variant alias strings from CDA entry `publish_details.variants` (requires fetches with the `x-cs-variant-uid` header set to aliases per [CDA variants](https://www.contentstack.com/docs/developers/apis/content-delivery-api#get-all-entry-variants)).
+
 ## [1.8.0](https://github.com/contentstack/contentstack-utils-javascript/tree/v1.8.0)
 - Fix: JSON-to-HTML now outputs valid HTML for nested lists when JSON RTE exports the nested list as a sibling of the preceding list item (`<li>`). The SDK folds such sibling `<ol>`/`<ul>` nodes into the previous `<li>` so the rendered HTML has the nested list inside the parent list item (PROD-2115).
 

__test__/mock/variant-fixtures.ts

@@ -0,0 +1,109 @@
+/** CDA-style fixtures aligned with variant utility spec / Java Utils tests. */
+
+export const variantEntrySingle = {
+  uid: 'entry_uid_single',
+  _metadata: {},
+  locale: 'en-us',
+  _version: 1,
+  ACL: {},
+  _in_progress: false,
+  title: 'Sample Movie',
+  created_at: '2025-11-20T10:00:00.000Z',
+  updated_at: '2025-12-11T07:56:17.574Z',
+  created_by: 'test_user',
+  updated_by: 'test_user',
+  publish_details: {
+    time: '2025-12-11T07:56:17.574Z',
+    user: 'test_user',
+    environment: 'test_env',
+    locale: 'en-us',
+    variants: {
+      cs_variant_0_0: {
+        alias: 'cs_personalize_0_0',
+        environment: 'test_env',
+        time: '2025-12-11T07:56:17.574Z',
+        locale: 'en-us',
+        user: 'test_user',
+        version: 1,
+      },
+      cs_variant_0_3: {
+        alias: 'cs_personalize_0_3',
+        environment: 'test_env',
+        time: '2025-12-11T07:56:17.582Z',
+        locale: 'en-us',
+        user: 'test_user',
+        version: 1,
+      },
+    },
+  },
+} as Record<string, unknown>;
+
+export const variantEntries = [
+  {
+    uid: 'entry_uid_1',
+    _metadata: {},
+    locale: 'en-us',
+    _version: 1,
+    title: 'Sample Movie',
+    publish_details: {
+      time: '2025-12-11T07:56:17.574Z',
+      user: 'test_user',
+      environment: 'test_env',
+      locale: 'en-us',
+      variants: {
+        cs_variant_0_0: {
+          alias: 'cs_personalize_0_0',
+          environment: 'test_env',
+          time: '2025-12-11T07:56:17.574Z',
+          locale: 'en-us',
+          user: 'test_user',
+          version: 1,
+        },
+        cs_variant_0_3: {
+          alias: 'cs_personalize_0_3',
+          environment: 'test_env',
+          time: '2025-12-11T07:56:17.582Z',
+          locale: 'en-us',
+          user: 'test_user',
+          version: 1,
+        },
+      },
+    },
+  },
+  {
+    uid: 'entry_uid_2',
+    _metadata: {},
+    locale: 'en-us',
+    _version: 2,
+    title: 'Another Movie',
+    publish_details: {
+      time: '2025-12-11T07:10:19.964Z',
+      user: 'test_user',
+      environment: 'test_env',
+      locale: 'en-us',
+      variants: {
+        cs_variant_0_0: {
+          alias: 'cs_personalize_0_0',
+          environment: 'test_env',
+          time: '2025-12-11T07:10:19.964Z',
+          locale: 'en-us',
+          user: 'test_user',
+          version: 2,
+        },
+      },
+    },
+  },
+  {
+    uid: 'entry_uid_3',
+    _metadata: {},
+    locale: 'en-us',
+    _version: 1,
+    title: 'Movie No Variants',
+    publish_details: {
+      time: '2025-11-20T10:00:00.000Z',
+      user: 'test_user',
+      environment: 'test_env',
+      locale: 'en-us',
+    },
+  },
+] as Record<string, unknown>[];

__test__/variant-aliases.test.ts

@@ -0,0 +1,136 @@
+import { getVariantAliases, getVariantMetadataTags } from '../src/variant-aliases';
+import { variantEntrySingle, variantEntries } from './mock/variant-fixtures';
+
+function sortAliases(aliases: string[]): string[] {
+  return [...aliases].sort((a, b) => a.localeCompare(b));
+}
+
+describe('getVariantAliases', () => {
+  const contentTypeUid = 'movie';
+
+  it('extracts variant aliases for a single entry with explicit contentTypeUid', () => {
+    const result = getVariantAliases(variantEntrySingle, contentTypeUid);
+    expect(result.entry_uid).toBe('entry_uid_single');
+    expect(result.contenttype_uid).toBe(contentTypeUid);
+    expect(sortAliases(result.variants)).toEqual(sortAliases(['cs_personalize_0_0', 'cs_personalize_0_3']));
+  });
+
+  it('uses _content_type_uid from entry when present', () => {
+    const entry = {
+      ...variantEntrySingle,
+      _content_type_uid: 'from_entry',
+    };
+    const result = getVariantAliases(entry, 'ignored');
+    expect(result.contenttype_uid).toBe('from_entry');
+  });
+
+  it('returns empty contenttype_uid when missing from entry and not passed', () => {
+    const result = getVariantAliases(variantEntrySingle);
+    expect(result.contenttype_uid).toBe('');
+  });
+
+  it('maps multiple entries in order', () => {
+    const results = getVariantAliases(variantEntries, contentTypeUid);
+    expect(results).toHaveLength(3);
+    expect(results[0].entry_uid).toBe('entry_uid_1');
+    expect(sortAliases(results[0].variants)).toEqual(sortAliases(['cs_personalize_0_0', 'cs_personalize_0_3']));
+    expect(results[1].entry_uid).toBe('entry_uid_2');
+    expect(results[1].variants).toEqual(['cs_personalize_0_0']);
+    expect(results[2].entry_uid).toBe('entry_uid_3');
+    expect(results[2].variants).toEqual([]);
+  });
+
+  it('returns empty variants when publish_details or variants is absent', () => {
+    const entry = { uid: 'u1', _content_type_uid: 'ct' };
+    expect(getVariantAliases(entry).variants).toEqual([]);
+    const entry2 = { uid: 'u1', publish_details: {} };
+    expect(getVariantAliases(entry2).variants).toEqual([]);
+    const entry3 = { uid: 'u1', publish_details: { variants: {} } };
+    expect(getVariantAliases(entry3).variants).toEqual([]);
+  });
+
+  it('skips variant objects with missing or empty alias', () => {
+    const entry = {
+      uid: 'u1',
+      publish_details: {
+        variants: {
+          a: { alias: 'keep_me' },
+          b: { alias: '' },
+          c: {},
+          d: { alias: 'also_keep' },
+        },
+      },
+    };
+    const result = getVariantAliases(entry);
+    expect(sortAliases(result.variants)).toEqual(sortAliases(['keep_me', 'also_keep']));
+  });
+
+  it('skips variant entries that are null, non-objects, or arrays', () => {
+    const variants: Record<string, unknown> = {
+      skip_null: null,
+      skip_string: 'not-an-object',
+      skip_array: [1, 2],
+      keep: { alias: 'only_valid' },
+    };
+    const entry = {
+      uid: 'u1',
+      publish_details: {
+        variants,
+      },
+    };
+    const result = getVariantAliases(entry);
+    expect(result.variants).toEqual(['only_valid']);
+  });
+
+  it('throws when entry is null or undefined', () => {
+    expect(() => getVariantAliases(null as unknown as Record<string, unknown>)).toThrow();
+    expect(() => getVariantAliases(undefined as unknown as Record<string, unknown>)).toThrow();
+  });
+
+  it('throws TypeError when single entry is a non-object (e.g. primitive)', () => {
+    expect(() => getVariantAliases(42 as unknown as Record<string, unknown>)).toThrow(TypeError);
+    expect(() => getVariantAliases('entry' as unknown as Record<string, unknown>)).toThrow(TypeError);
+  });
+
+  it('throws TypeError when an array item is not a plain object', () => {
+    expect(() =>
+      getVariantAliases([variantEntrySingle, [] as unknown as Record<string, unknown>])
+    ).toThrow(TypeError);
+  });
+
+  it('throws when entry uid is missing or empty', () => {
+    expect(() => getVariantAliases({})).toThrow(/uid/i);
+    expect(() => getVariantAliases({ uid: '' })).toThrow(/uid/i);
+  });
+
+  it('throws when entries array contains a non-object', () => {
+    expect(() => getVariantAliases([variantEntrySingle, null as unknown as Record<string, unknown>])).toThrow();
+  });
+});
+
+describe('getVariantMetadataTags', () => {
+  const contentTypeUid = 'movie';
+
+  it('serialises array results as JSON in data-csvariants', () => {
+    const tag = getVariantMetadataTags(variantEntries, contentTypeUid);
+    expect(tag).toHaveProperty('data-csvariants');
+    const parsed = JSON.parse(tag['data-csvariants']) as Array<{
+      entry_uid: string;
+      contenttype_uid: string;
+      variants: string[];
+    }>;
+    expect(parsed).toHaveLength(3);
+    expect(parsed[0].entry_uid).toBe('entry_uid_1');
+    expect(sortAliases(parsed[0].variants)).toEqual(sortAliases(['cs_personalize_0_0', 'cs_personalize_0_3']));
+  });
+
+  it('returns empty JSON array string for empty entries', () => {
+    const tag = getVariantMetadataTags([]);
+    expect(tag['data-csvariants']).toBe('[]');
+  });
+
+  it('throws when entries is null or not an array', () => {
+    expect(() => getVariantMetadataTags(null as unknown as Record<string, unknown>[])).toThrow();
+    expect(() => getVariantMetadataTags({} as unknown as Record<string, unknown>[])).toThrow();
+  });
+});

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@contentstack/utils",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "Contentstack utilities for Javascript",
   "main": "dist/index.es.js",
   "types": "dist/types/index.d.ts",

package.json

@@ -14,4 +14,6 @@ export { jsonToHTML } from './json-to-html'
 export { GQL } from './gql'
 export { addTags as addEditableTags } from './entry-editable'
 export { updateAssetURLForGQL } from './updateAssetURLForGQL'
-export { getContentstackEndpoint, ContentstackEndpoints } from './endpoints'
+export { getContentstackEndpoint, ContentstackEndpoints } from './endpoints'
+export { getVariantAliases, getVariantMetadataTags } from './variant-aliases'
+export type { VariantAliasesResult, CDAEntryLike } from './variant-aliases'