@starlightcms/js-sdk 4.0.0-beta.0 → 4.0.0-beta.1

package/dist/cjs/types/utilities.d.ts

@@ -6,7 +6,7 @@ import { RepeaterGroup } from './groups';
  * the `Foo` type. This is useful to "pick" the type of the content held
  * by items of a Repeater Group.
  *
- * @group Utilities
+ * @group Utility Types
  */
 export type RepeaterItem<Repeater extends RepeaterGroup<Record<string, unknown>>> = Repeater extends readonly (infer ItemType)[] ? ItemType : never;
 //# sourceMappingURL=utilities.d.ts.map

package/dist/cjs/types/utilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utilities\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utility Types\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}

package/dist/cjs/utils/image.d.ts

@@ -1,4 +1,72 @@
 import { MediaFile, MediaObject } from '../types';
-export declare const getMediaFile: (media: MediaObject, variation?: string) => MediaFile;
-export declare const getMediaSource: (media: MediaObject, variation?: string) => string;
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare const getMediaFile: (media?: MediaObject, variation?: string | string[]) => MediaFile | undefined;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare function getMediaSource(media?: MediaObject, variation?: string | string[]): string | undefined;
 //# sourceMappingURL=image.d.ts.map

package/dist/cjs/utils/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AASjD,eAAO,MAAM,YAAY,GACvB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,SASF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,MAEF,CAAA"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,MAAM,EAAE,KAC5B,SAAS,GAAG,SAgBd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,CAAC,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,sBAG9B"}

package/dist/cjs/utils/image.js

@@ -1,20 +1,101 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getMediaSource = exports.getMediaFile = void 0;
+exports.getMediaFile = void 0;
+exports.getMediaSource = getMediaSource;
+/**
+ * Returns the optimized variation file of the given MediaObject
+ * or the original file if the optimized variation doesn't exist.
+ *
+ * @param media The MediaObject to analyze.
+ */
 const getOptimizedOrOriginal = (media) => {
     var _a;
     return ((_a = media.files.find((file) => file.variation === 'optimized')) !== null && _a !== void 0 ? _a : media.files.find((file) => file.variation === 'original'));
 };
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
 const getMediaFile = (media, variation) => {
-    var _a;
+    if (!media)
+        return undefined;
     if (variation) {
-        return ((_a = media.files.find((file) => file.variation === variation)) !== null && _a !== void 0 ? _a : getOptimizedOrOriginal(media));
+        const variationArray = Array.isArray(variation) ? variation : [variation];
+        for (const variationName of variationArray) {
+            const file = media.files.find((file) => file.variation === variationName);
+            if (file) {
+                return file;
+            }
+        }
     }
     return getOptimizedOrOriginal(media);
 };
 exports.getMediaFile = getMediaFile;
-const getMediaSource = (media, variation) => {
-    return (0, exports.getMediaFile)(media, variation).path;
-};
-exports.getMediaSource = getMediaSource;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+function getMediaSource(media, variation) {
+    return media ? (0, exports.getMediaFile)(media, variation).path : undefined;
+}
 //# sourceMappingURL=image.js.map

package/dist/cjs/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":";;;AAEA,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAEM,MAAM,YAAY,GAAG,CAC1B,KAAkB,EAClB,SAAkB,EACP,EAAE;;IACb,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,mCACxD,sBAAsB,CAAC,KAAK,CAAC,CAC9B,CAAA;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAZY,QAAA,YAAY,gBAYxB;AAEM,MAAM,cAAc,GAAG,CAC5B,KAAkB,EAClB,SAAkB,EACV,EAAE;IACV,OAAO,IAAA,oBAAY,EAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC,CAAA;AALY,QAAA,cAAc,kBAK1B","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\nexport const getMediaFile = (\n  media: MediaObject,\n  variation?: string\n): MediaFile => {\n  if (variation) {\n    return (\n      media.files.find((file) => file.variation === variation) ??\n      getOptimizedOrOriginal(media)\n    )\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\nexport const getMediaSource = (\n  media: MediaObject,\n  variation?: string\n): string => {\n  return getMediaFile(media, variation).path\n}\n"]}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":";;;AAwGA,wCAKC;AA3GD;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACI,MAAM,YAAY,GAAG,CAC1B,KAAmB,EACnB,SAA6B,EACN,EAAE;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAE5B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAEzE,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,aAAa,CAAC,CAAA;YAEzE,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAnBY,QAAA,YAAY,gBAmBxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,SAAgB,cAAc,CAC5B,KAAmB,EACnB,SAA6B;IAE7B,OAAO,KAAK,CAAC,CAAC,CAAC,IAAA,oBAAY,EAAC,KAAK,EAAE,SAAS,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\n/**\n * Returns the optimized variation file of the given MediaObject\n * or the original file if the optimized variation doesn't exist.\n *\n * @param media The MediaObject to analyze.\n */\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\n/**\n * Returns the given variation of the provided MediaObject.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The MediaFile of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation file (if it exists) or the original file. Returns\n * undefined if no media object is provided.\n *\n * @example Getting the optimized or original file of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `info.featured_image` is the path of an arbitrary Media content field.\n * const file = getMediaFile(response.data.data.info.featured_image)\n * ```\n *\n * @category Media Utilities\n */\nexport const getMediaFile = (\n  media?: MediaObject,\n  variation?: string | string[],\n): MediaFile | undefined => {\n  if (!media) return undefined\n\n  if (variation) {\n    const variationArray = Array.isArray(variation) ? variation : [variation]\n\n    for (const variationName of variationArray) {\n      const file = media.files.find((file) => file.variation === variationName)\n\n      if (file) {\n        return file\n      }\n    }\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\n/**\n * Returns the source URL of the optimized file (if it exists) or the original\n * file of the given MediaObject. If the variation parameter is provided,\n * returns the source URL of that variation instead, if it exists, but falls\n * back to the optimized or original files if it doesn't.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The source URL of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation source URL (if it exists) or the original source URL.\n * Returns undefined if no media object is provided.\n *\n * @example Getting the optimized or original source URL of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(response.data.data.content.background)\n * ```\n *\n * @example Getting the source URL of a specific variation of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(\n *   response.data.data.content.background,\n *   ['large', 'medium']\n * )\n * ```\n *\n * @category Media Utilities\n */\nexport function getMediaSource(\n  media?: MediaObject,\n  variation?: string | string[],\n) {\n  return media ? getMediaFile(media, variation)!.path : undefined\n}\n"]}

package/dist/esm/types/utilities.d.ts

@@ -6,7 +6,7 @@ import { RepeaterGroup } from './groups';
  * the `Foo` type. This is useful to "pick" the type of the content held
  * by items of a Repeater Group.
  *
- * @group Utilities
+ * @group Utility Types
  */
 export type RepeaterItem<Repeater extends RepeaterGroup<Record<string, unknown>>> = Repeater extends readonly (infer ItemType)[] ? ItemType : never;
 //# sourceMappingURL=utilities.d.ts.map

package/dist/esm/types/utilities.js.map

@@ -1 +1 @@
-{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utilities\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}
+{"version":3,"file":"utilities.js","sourceRoot":"","sources":["../../../src/types/utilities.ts"],"names":[],"mappings":"","sourcesContent":["import { RepeaterGroup } from './groups'\n\n/**\n * Returns the item type of the given Repeater Group.\n *\n * For instance, given a `RepeaterGroup<Foo>`, this utility would return\n * the `Foo` type. This is useful to \"pick\" the type of the content held\n * by items of a Repeater Group.\n *\n * @group Utility Types\n */\nexport type RepeaterItem<\n  Repeater extends RepeaterGroup<Record<string, unknown>>,\n> = Repeater extends readonly (infer ItemType)[] ? ItemType : never\n"]}

package/dist/esm/utils/image.d.ts

@@ -1,4 +1,72 @@
 import { MediaFile, MediaObject } from '../types';
-export declare const getMediaFile: (media: MediaObject, variation?: string) => MediaFile;
-export declare const getMediaSource: (media: MediaObject, variation?: string) => string;
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare const getMediaFile: (media?: MediaObject, variation?: string | string[]) => MediaFile | undefined;
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export declare function getMediaSource(media?: MediaObject, variation?: string | string[]): string | undefined;
 //# sourceMappingURL=image.d.ts.map

package/dist/esm/utils/image.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AASjD,eAAO,MAAM,YAAY,GACvB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,SASF,CAAA;AAED,eAAO,MAAM,cAAc,GACzB,OAAO,WAAW,EAClB,YAAY,MAAM,KACjB,MAEF,CAAA"}
+{"version":3,"file":"image.d.ts","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAejD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,WAAW,EACnB,YAAY,MAAM,GAAG,MAAM,EAAE,KAC5B,SAAS,GAAG,SAgBd,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,cAAc,CAC5B,KAAK,CAAC,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,sBAG9B"}

package/dist/esm/utils/image.js

@@ -1,15 +1,96 @@
+/**
+ * Returns the optimized variation file of the given MediaObject
+ * or the original file if the optimized variation doesn't exist.
+ *
+ * @param media The MediaObject to analyze.
+ */
 const getOptimizedOrOriginal = (media) => {
     var _a;
     return ((_a = media.files.find((file) => file.variation === 'optimized')) !== null && _a !== void 0 ? _a : media.files.find((file) => file.variation === 'original'));
 };
+/**
+ * Returns the given variation of the provided MediaObject.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The MediaFile of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation file (if it exists) or the original file. Returns
+ * undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original file of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `info.featured_image` is the path of an arbitrary Media content field.
+ * const file = getMediaFile(response.data.data.info.featured_image)
+ * ```
+ *
+ * @category Media Utilities
+ */
 export const getMediaFile = (media, variation) => {
-    var _a;
+    if (!media)
+        return undefined;
     if (variation) {
-        return ((_a = media.files.find((file) => file.variation === variation)) !== null && _a !== void 0 ? _a : getOptimizedOrOriginal(media));
+        const variationArray = Array.isArray(variation) ? variation : [variation];
+        for (const variationName of variationArray) {
+            const file = media.files.find((file) => file.variation === variationName);
+            if (file) {
+                return file;
+            }
+        }
     }
     return getOptimizedOrOriginal(media);
 };
-export const getMediaSource = (media, variation) => {
-    return getMediaFile(media, variation).path;
-};
+/**
+ * Returns the source URL of the optimized file (if it exists) or the original
+ * file of the given MediaObject. If the variation parameter is provided,
+ * returns the source URL of that variation instead, if it exists, but falls
+ * back to the optimized or original files if it doesn't.
+ *
+ * @param media The MediaObject to analyze. If undefined, the function will also
+ * return undefined.
+ * @param variation A string or array of strings with the variation name that
+ * should be returned. If an array is given, the first variation found will
+ * be returned.
+ *
+ * @returns The source URL of the first given variation found. If the provided
+ * variations weren't found, or if no variation parameter was provided, returns
+ * the optimized variation source URL (if it exists) or the original source URL.
+ * Returns undefined if no media object is provided.
+ *
+ * @example Getting the optimized or original source URL of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(response.data.data.content.background)
+ * ```
+ *
+ * @example Getting the source URL of a specific variation of the given MediaObject.
+ * ```ts
+ * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'
+ *
+ * const response = await Starlight.posts.entries.get('foo')
+ *
+ * // `content.background` is the path of an arbitrary Media content field.
+ * const imageUrl = getMediaSource(
+ *   response.data.data.content.background,
+ *   ['large', 'medium']
+ * )
+ * ```
+ *
+ * @category Media Utilities
+ */
+export function getMediaSource(media, variation) {
+    return media ? getMediaFile(media, variation).path : undefined;
+}
 //# sourceMappingURL=image.js.map

package/dist/esm/utils/image.js.map

@@ -1 +1 @@
-{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAEA,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAkB,EAClB,SAAkB,EACP,EAAE;;IACb,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,CAAC,mCACxD,sBAAsB,CAAC,KAAK,CAAC,CAC9B,CAAA;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,cAAc,GAAG,CAC5B,KAAkB,EAClB,SAAkB,EACV,EAAE;IACV,OAAO,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC,IAAI,CAAA;AAC5C,CAAC,CAAA","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\nexport const getMediaFile = (\n  media: MediaObject,\n  variation?: string\n): MediaFile => {\n  if (variation) {\n    return (\n      media.files.find((file) => file.variation === variation) ??\n      getOptimizedOrOriginal(media)\n    )\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\nexport const getMediaSource = (\n  media: MediaObject,\n  variation?: string\n): string => {\n  return getMediaFile(media, variation).path\n}\n"]}
+{"version":3,"file":"image.js","sourceRoot":"","sources":["../../../src/utils/image.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,CAAC,KAAkB,EAAE,EAAE;;IACpD,OAAO,CACL,MAAA,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,WAAW,CAAC,mCACzD,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,UAAU,CAAe,CACzE,CAAA;AACH,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,CAC1B,KAAmB,EACnB,SAA6B,EACN,EAAE;IACzB,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAA;IAE5B,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,cAAc,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAEzE,KAAK,MAAM,aAAa,IAAI,cAAc,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,SAAS,KAAK,aAAa,CAAC,CAAA;YAEzE,IAAI,IAAI,EAAE,CAAC;gBACT,OAAO,IAAI,CAAA;YACb,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,sBAAsB,CAAC,KAAK,CAAC,CAAA;AACtC,CAAC,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,MAAM,UAAU,cAAc,CAC5B,KAAmB,EACnB,SAA6B;IAE7B,OAAO,KAAK,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;AACjE,CAAC","sourcesContent":["import { MediaFile, MediaObject } from '../types'\n\n/**\n * Returns the optimized variation file of the given MediaObject\n * or the original file if the optimized variation doesn't exist.\n *\n * @param media The MediaObject to analyze.\n */\nconst getOptimizedOrOriginal = (media: MediaObject) => {\n  return (\n    media.files.find((file) => file.variation === 'optimized') ??\n    (media.files.find((file) => file.variation === 'original') as MediaFile)\n  )\n}\n\n/**\n * Returns the given variation of the provided MediaObject.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The MediaFile of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation file (if it exists) or the original file. Returns\n * undefined if no media object is provided.\n *\n * @example Getting the optimized or original file of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaFile } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `info.featured_image` is the path of an arbitrary Media content field.\n * const file = getMediaFile(response.data.data.info.featured_image)\n * ```\n *\n * @category Media Utilities\n */\nexport const getMediaFile = (\n  media?: MediaObject,\n  variation?: string | string[],\n): MediaFile | undefined => {\n  if (!media) return undefined\n\n  if (variation) {\n    const variationArray = Array.isArray(variation) ? variation : [variation]\n\n    for (const variationName of variationArray) {\n      const file = media.files.find((file) => file.variation === variationName)\n\n      if (file) {\n        return file\n      }\n    }\n  }\n\n  return getOptimizedOrOriginal(media)\n}\n\n/**\n * Returns the source URL of the optimized file (if it exists) or the original\n * file of the given MediaObject. If the variation parameter is provided,\n * returns the source URL of that variation instead, if it exists, but falls\n * back to the optimized or original files if it doesn't.\n *\n * @param media The MediaObject to analyze. If undefined, the function will also\n * return undefined.\n * @param variation A string or array of strings with the variation name that\n * should be returned. If an array is given, the first variation found will\n * be returned.\n *\n * @returns The source URL of the first given variation found. If the provided\n * variations weren't found, or if no variation parameter was provided, returns\n * the optimized variation source URL (if it exists) or the original source URL.\n * Returns undefined if no media object is provided.\n *\n * @example Getting the optimized or original source URL of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(response.data.data.content.background)\n * ```\n *\n * @example Getting the source URL of a specific variation of the given MediaObject.\n * ```ts\n * import Starlight, { getMediaSource } from '@starlightcms/js-sdk'\n *\n * const response = await Starlight.posts.entries.get('foo')\n *\n * // `content.background` is the path of an arbitrary Media content field.\n * const imageUrl = getMediaSource(\n *   response.data.data.content.background,\n *   ['large', 'medium']\n * )\n * ```\n *\n * @category Media Utilities\n */\nexport function getMediaSource(\n  media?: MediaObject,\n  variation?: string | string[],\n) {\n  return media ? getMediaFile(media, variation)!.path : undefined\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starlightcms/js-sdk",
-  "version": "4.0.0-beta.0",
+  "version": "4.0.0-beta.1",
   "description": "The Starlight SDK for JavaScript",
   "main": "dist/cjs/index.js",
   "exports": {