|
| 1 | +/** |
| 2 | + * Shape returned by {@link getVariantAliases} for interoperability with other Utils SDKs (snake_case JSON keys). |
| 3 | + */ |
| 4 | +export interface VariantAliasesResult { |
| 5 | + entry_uid: string; |
| 6 | + contenttype_uid: string; |
| 7 | + variants: string[]; |
| 8 | +} |
| 9 | + |
| 10 | +/** CDA entry JSON: at minimum includes `uid`; may include `_content_type_uid` and `publish_details.variants`. */ |
| 11 | +export type CDAEntryLike = Record<string, unknown>; |
| 12 | + |
| 13 | +function assertPlainObject(value: unknown, message: string): asserts value is Record<string, unknown> { |
| 14 | + if (value === null || value === undefined) { |
| 15 | + throw new TypeError(message); |
| 16 | + } |
| 17 | + if (typeof value !== 'object' || Array.isArray(value)) { |
| 18 | + throw new TypeError(message); |
| 19 | + } |
| 20 | +} |
| 21 | + |
| 22 | +function requireEntryUid(entry: Record<string, unknown>): string { |
| 23 | + const uid = entry.uid; |
| 24 | + if (typeof uid !== 'string' || uid.length === 0) { |
| 25 | + throw new Error('Entry uid is required. The entry must include a non-empty uid string.'); |
| 26 | + } |
| 27 | + return uid; |
| 28 | +} |
| 29 | + |
| 30 | +function resolveContentTypeUid(entry: Record<string, unknown>, contentTypeUid?: string): string { |
| 31 | + const fromEntry = entry._content_type_uid; |
| 32 | + if (typeof fromEntry === 'string' && fromEntry.length > 0) { |
| 33 | + return fromEntry; |
| 34 | + } |
| 35 | + if (typeof contentTypeUid === 'string' && contentTypeUid.length > 0) { |
| 36 | + return contentTypeUid; |
| 37 | + } |
| 38 | + return ''; |
| 39 | +} |
| 40 | + |
| 41 | +function collectVariantAliases(entry: Record<string, unknown>): string[] { |
| 42 | + const publishDetails = entry.publish_details; |
| 43 | + if (!publishDetails || typeof publishDetails !== 'object' || Array.isArray(publishDetails)) { |
| 44 | + return []; |
| 45 | + } |
| 46 | + const variants = (publishDetails as Record<string, unknown>).variants; |
| 47 | + if (!variants || typeof variants !== 'object' || Array.isArray(variants)) { |
| 48 | + return []; |
| 49 | + } |
| 50 | + const out: string[] = []; |
| 51 | + const map = variants as Record<string, unknown>; |
| 52 | + for (const key of Object.keys(map)) { |
| 53 | + const v = map[key]; |
| 54 | + if (!v || typeof v !== 'object' || Array.isArray(v)) { |
| 55 | + continue; |
| 56 | + } |
| 57 | + const alias = (v as { alias?: unknown }).alias; |
| 58 | + if (typeof alias === 'string' && alias.length > 0) { |
| 59 | + out.push(alias); |
| 60 | + } |
| 61 | + } |
| 62 | + return out; |
| 63 | +} |
| 64 | + |
| 65 | +function mapEntryToResult(entry: Record<string, unknown>, contentTypeUid?: string): VariantAliasesResult { |
| 66 | + return { |
| 67 | + entry_uid: requireEntryUid(entry), |
| 68 | + contenttype_uid: resolveContentTypeUid(entry, contentTypeUid), |
| 69 | + variants: collectVariantAliases(entry), |
| 70 | + }; |
| 71 | +} |
| 72 | + |
| 73 | +/** |
| 74 | + * Extracts variant **alias** strings from `publish_details.variants` on a CDA entry. |
| 75 | + * Only present when the entry was fetched with the `x-cs-variant-uid` header set to variant **aliases** (not UIDs). |
| 76 | + * |
| 77 | + * @param entry - Single CDA entry object (must include `uid`). |
| 78 | + * @param contentTypeUid - Used when `entry._content_type_uid` is missing. Otherwise omitted or empty string yields `contenttype_uid: ""`. |
| 79 | + * @returns `{ entry_uid, contenttype_uid, variants }` with snake_case keys for cross-SDK JSON parity. |
| 80 | + * @throws TypeError if `entry` is null/undefined or not a plain object. |
| 81 | + * @throws Error if `entry` has no non-empty `uid`. |
| 82 | + */ |
| 83 | +export function getVariantAliases(entry: CDAEntryLike, contentTypeUid?: string): VariantAliasesResult; |
| 84 | + |
| 85 | +/** |
| 86 | + * Extracts variant aliases for each entry in order. |
| 87 | + * |
| 88 | + * @param entries - Array of CDA entry objects. |
| 89 | + * @param contentTypeUid - Applied when an entry lacks `_content_type_uid`. |
| 90 | + * @returns One result object per input entry. |
| 91 | + * @throws TypeError if `entries` is null/undefined or not an array, or any element is not a plain object. |
| 92 | + * @throws Error if any entry has no non-empty `uid`. |
| 93 | + */ |
| 94 | +export function getVariantAliases(entries: CDAEntryLike[], contentTypeUid?: string): VariantAliasesResult[]; |
| 95 | + |
| 96 | +export function getVariantAliases( |
| 97 | + entryOrEntries: CDAEntryLike | CDAEntryLike[], |
| 98 | + contentTypeUid?: string |
| 99 | +): VariantAliasesResult | VariantAliasesResult[] { |
| 100 | + if (Array.isArray(entryOrEntries)) { |
| 101 | + return entryOrEntries.map((e) => { |
| 102 | + assertPlainObject(e, 'Each entry must be a plain object with a uid.'); |
| 103 | + return mapEntryToResult(e, contentTypeUid); |
| 104 | + }); |
| 105 | + } |
| 106 | + assertPlainObject(entryOrEntries, 'Entry is required. Provide a CDA entry object with a uid.'); |
| 107 | + return mapEntryToResult(entryOrEntries, contentTypeUid); |
| 108 | +} |
| 109 | + |
| 110 | +/** |
| 111 | + * Serialises variant alias results for use as an HTML `data-csvariants` attribute value. |
| 112 | + * |
| 113 | + * @param entries - CDA entries to process (same rules as {@link getVariantAliases} for each item). |
| 114 | + * @param contentTypeUid - Applied when an entry lacks `_content_type_uid`. |
| 115 | + * @returns `{ "data-csvariants": "<JSON string of VariantAliasesResult[]>" }`. |
| 116 | + * @throws TypeError if `entries` is null/undefined or not an array, or any element is not a plain object. |
| 117 | + * @throws Error if any entry has no non-empty `uid`. |
| 118 | + */ |
| 119 | +export function getVariantMetadataTags( |
| 120 | + entries: CDAEntryLike[], |
| 121 | + contentTypeUid?: string |
| 122 | +): { 'data-csvariants': string } { |
| 123 | + if (entries === null || entries === undefined) { |
| 124 | + throw new TypeError('Entries array is required. Provide an array of CDA entry objects.'); |
| 125 | + } |
| 126 | + if (!Array.isArray(entries)) { |
| 127 | + throw new TypeError('Entries must be an array of CDA entry objects.'); |
| 128 | + } |
| 129 | + const payload = getVariantAliases(entries, contentTypeUid); |
| 130 | + return { 'data-csvariants': JSON.stringify(payload) }; |
| 131 | +} |
0 commit comments