@prismicio/types-internal 2.7.0 → 2.9.0-alpha.0

package/lib/content/fields/nestable/LinkContent.d.ts

@@ -1,10 +1,33 @@
+/**
+ * LinkContent is a union of different link content types.
+ *
+ * Most link content types are built from a union of a filled and an unfilled version.
+ *
+ * Filled versions make sure that the important fields that make the link work
+ * are present. They are also exported for when there's a need to ensure that
+ * the link is filled when used in a specific context, e.g. links in rich text fields.
+ *
+ * Unfilled versions are used when the link is not filled yet but contains other
+ * information like the text.
+ *
+ * There are some exceptions that don't have a filled version (e.g. MediaLink)
+ * for when the exact subtype is not yet known.
+ *
+ * Unfilled versions all have a special `kind` property that is used to
+ * determine the type of the link. For legacy reasons, filled versions don't
+ * necessarily require this property or its type is loose (e.g. `string`). In
+ * this cases, the type is determined based on a specific combination of the
+ * rest of the link data. This is why the order of the subtypes in the union is
+ * important and should be from the most specific to the least specific. A
+ * battery of tests ensures that the correct type is inferred.
+ */
 import * as t from "io-ts";
 import type { LegacyContentCtx, WithTypes } from "../../LegacyContentCtx";
 export declare const ImageLinkType = "ImageLink";
 export declare const FilledImageLinkContent: t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"ImageLink">;
 }>>, t.IntersectionC<[t.ExactC<t.TypeC<{
-    kind: t.Type<"image", "image", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     height: t.StringC;
@@ -18,7 +41,7 @@ export declare type FilledImageLinkContent = t.TypeOf<typeof FilledImageLinkCont
 export declare const ImageLinkContent: t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"ImageLink">;
 }>>, t.UnionC<[t.IntersectionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
-    kind: t.Type<"image", "image", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     height: t.StringC;
@@ -38,7 +61,7 @@ export declare const FileLinkType = "FileLink";
 export declare const FilledFileLinkContent: t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"FileLink">;
 }>>, t.ExactC<t.IntersectionC<[t.TypeC<{
-    kind: t.Type<"file", "file", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     name: t.StringC;
@@ -50,7 +73,7 @@ export declare type FilledFileLinkContent = t.TypeOf<typeof FilledFileLinkConten
 export declare const FileLinkContent: t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"FileLink">;
 }>>, t.UnionC<[t.IntersectionC<[t.ExactC<t.IntersectionC<[t.TypeC<{
-    kind: t.Type<"file", "file", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     name: t.StringC;
@@ -137,7 +160,7 @@ export declare const isLinkContent: (u: unknown) => u is {
     value: ({
         __TYPE__: "ImageLink";
     } & (({
-        kind: "image";
+        kind: string;
         id: string;
         url: string;
         height: string;
@@ -154,7 +177,7 @@ export declare const isLinkContent: (u: unknown) => u is {
     })) | ({
         __TYPE__: "FileLink";
     } & (({
-        kind: "file";
+        kind: string;
         id: string;
         url: string;
         name: string;
@@ -204,7 +227,7 @@ export declare const isLinkContent: (u: unknown) => u is {
 export declare const LinkLegacy: t.UnionC<[t.Type<{
     __TYPE__: "ImageLink";
 } & (({
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -219,7 +242,7 @@ export declare const LinkLegacy: t.UnionC<[t.Type<{
     kind: "image";
     text: string;
 }), ({
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -236,7 +259,7 @@ export declare const LinkLegacy: t.UnionC<[t.Type<{
 }, unknown>, t.Type<{
     __TYPE__: "FileLink";
 } & (({
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -249,7 +272,7 @@ export declare const LinkLegacy: t.UnionC<[t.Type<{
     kind: "file";
     text: string;
 }), ({
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -325,7 +348,7 @@ export declare const LinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<{
     value: ({
         __TYPE__: "ImageLink";
     } & (({
-        kind: "image";
+        kind: string;
         id: string;
         url: string;
         height: string;
@@ -342,7 +365,7 @@ export declare const LinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<{
     })) | ({
         __TYPE__: "FileLink";
     } & (({
-        kind: "file";
+        kind: string;
         id: string;
         url: string;
         name: string;
@@ -389,7 +412,7 @@ export declare const LinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<{
         text: string;
     });
 }, WithTypes<({
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -404,7 +427,7 @@ export declare const LinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<{
     kind: "image";
     text: string;
 } | ({
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -445,7 +468,7 @@ export declare const LinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<{
 export declare const Link: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"ImageLink">;
 }>>, t.UnionC<[t.IntersectionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
-    kind: t.Type<"image", "image", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     height: t.StringC;
@@ -462,7 +485,7 @@ export declare const Link: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
 }>>]>]>, t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"FileLink">;
 }>>, t.UnionC<[t.IntersectionC<[t.ExactC<t.IntersectionC<[t.TypeC<{
-    kind: t.Type<"file", "file", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     name: t.StringC;
@@ -515,7 +538,7 @@ export declare const LinkContent: t.ExactC<t.TypeC<{
     value: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
         __TYPE__: t.LiteralC<"ImageLink">;
     }>>, t.UnionC<[t.IntersectionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
-        kind: t.Type<"image", "image", unknown>;
+        kind: t.StringC;
         id: t.StringC;
         url: t.StringC;
         height: t.StringC;
@@ -532,7 +555,7 @@ export declare const LinkContent: t.ExactC<t.TypeC<{
     }>>]>]>, t.IntersectionC<[t.ExactC<t.TypeC<{
         __TYPE__: t.LiteralC<"FileLink">;
     }>>, t.UnionC<[t.IntersectionC<[t.ExactC<t.IntersectionC<[t.TypeC<{
-        kind: t.Type<"file", "file", unknown>;
+        kind: t.StringC;
         id: t.StringC;
         url: t.StringC;
         name: t.StringC;
@@ -588,7 +611,7 @@ export declare const isFilledLinkContent: (u: unknown) => u is {
     value: ({
         __TYPE__: "ImageLink";
     } & {
-        kind: "image";
+        kind: string;
         id: string;
         url: string;
         height: string;
@@ -600,7 +623,7 @@ export declare const isFilledLinkContent: (u: unknown) => u is {
     }) | ({
         __TYPE__: "FileLink";
     } & {
-        kind: "file";
+        kind: string;
         id: string;
         url: string;
         name: string;
@@ -626,7 +649,7 @@ export declare const isFilledLinkContent: (u: unknown) => u is {
 export declare const FilledLinkLegacy: t.UnionC<[t.Type<{
     __TYPE__: "ImageLink";
 } & {
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -636,7 +659,7 @@ export declare const FilledLinkLegacy: t.UnionC<[t.Type<{
 } & {
     date?: string | null | undefined;
 }, {
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -648,7 +671,7 @@ export declare const FilledLinkLegacy: t.UnionC<[t.Type<{
 }, unknown>, t.Type<{
     __TYPE__: "FileLink";
 } & {
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -656,7 +679,7 @@ export declare const FilledLinkLegacy: t.UnionC<[t.Type<{
 } & {
     date?: string | null | undefined;
 }, {
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -693,7 +716,7 @@ export declare const FilledLinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<
     value: ({
         __TYPE__: "ImageLink";
     } & {
-        kind: "image";
+        kind: string;
         id: string;
         url: string;
         height: string;
@@ -705,7 +728,7 @@ export declare const FilledLinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<
     }) | ({
         __TYPE__: "FileLink";
     } & {
-        kind: "file";
+        kind: string;
         id: string;
         url: string;
         name: string;
@@ -728,7 +751,7 @@ export declare const FilledLinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<
         } | null | undefined;
     });
 }, WithTypes<({
-    kind: "image";
+    kind: string;
     id: string;
     url: string;
     height: string;
@@ -738,7 +761,7 @@ export declare const FilledLinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<
 } & {
     date?: string | null | undefined;
 }) | ({
-    kind: "file";
+    kind: string;
     id: string;
     url: string;
     name: string;
@@ -759,7 +782,7 @@ export declare const FilledLinkContentLegacy: (ctx: LegacyContentCtx) => t.Type<
 export declare const FilledLink: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"ImageLink">;
 }>>, t.IntersectionC<[t.ExactC<t.TypeC<{
-    kind: t.Type<"image", "image", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     height: t.StringC;
@@ -771,7 +794,7 @@ export declare const FilledLink: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
 }>>]>]>, t.IntersectionC<[t.ExactC<t.TypeC<{
     __TYPE__: t.LiteralC<"FileLink">;
 }>>, t.ExactC<t.IntersectionC<[t.TypeC<{
-    kind: t.Type<"file", "file", unknown>;
+    kind: t.StringC;
     id: t.StringC;
     url: t.StringC;
     name: t.StringC;
@@ -800,7 +823,7 @@ export declare const FilledLinkContent: t.ExactC<t.TypeC<{
     value: t.UnionC<[t.IntersectionC<[t.ExactC<t.TypeC<{
         __TYPE__: t.LiteralC<"ImageLink">;
     }>>, t.IntersectionC<[t.ExactC<t.TypeC<{
-        kind: t.Type<"image", "image", unknown>;
+        kind: t.StringC;
         id: t.StringC;
         url: t.StringC;
         height: t.StringC;
@@ -812,7 +835,7 @@ export declare const FilledLinkContent: t.ExactC<t.TypeC<{
     }>>]>]>, t.IntersectionC<[t.ExactC<t.TypeC<{
         __TYPE__: t.LiteralC<"FileLink">;
     }>>, t.ExactC<t.IntersectionC<[t.TypeC<{
-        kind: t.Type<"file", "file", unknown>;
+        kind: t.StringC;
         id: t.StringC;
         url: t.StringC;
         name: t.StringC;

package/lib/content/fields/nestable/LinkContent.js

@@ -1,4 +1,27 @@
 "use strict";
+/**
+ * LinkContent is a union of different link content types.
+ *
+ * Most link content types are built from a union of a filled and an unfilled version.
+ *
+ * Filled versions make sure that the important fields that make the link work
+ * are present. They are also exported for when there's a need to ensure that
+ * the link is filled when used in a specific context, e.g. links in rich text fields.
+ *
+ * Unfilled versions are used when the link is not filled yet but contains other
+ * information like the text.
+ *
+ * There are some exceptions that don't have a filled version (e.g. MediaLink)
+ * for when the exact subtype is not yet known.
+ *
+ * Unfilled versions all have a special `kind` property that is used to
+ * determine the type of the link. For legacy reasons, filled versions don't
+ * necessarily require this property or its type is loose (e.g. `string`). In
+ * this cases, the type is determined based on a specific combination of the
+ * rest of the link data. This is why the order of the subtypes in the union is
+ * important and should be from the most specific to the least specific. A
+ * battery of tests ensures that the correct type is inferred.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FilledLinkContent = exports.FilledLink = exports.FilledLinkContentLegacy = exports.FilledLinkLegacy = exports.isFilledLinkContent = exports.LinkContent = exports.Link = exports.LinkContentLegacy = exports.LinkLegacy = exports.isLinkContent = exports.LinkContentType = exports.AnyLinkContent = exports.AnyLinkType = exports.ExternalLinkContent = exports.FilledExternalLinkContent = exports.ExternalLinkType = exports.DocumentLinkContent = exports.FilledDocumentLinkContent = exports.DocumentLinkType = exports.MediaLinkContent = exports.MediaLinkType = exports.FileLinkContent = exports.FilledFileLinkContent = exports.FileLinkType = exports.ImageLinkContent = exports.FilledImageLinkContent = exports.ImageLinkType = void 0;
 const tslib_1 = require("tslib");
@@ -11,13 +34,9 @@ const function_2 = require("../../../validators/function");
 const utils_1 = require("../../utils");
 // ImageLink.
 exports.ImageLinkType = "ImageLink";
-const isImageLinkKind = (input) => typeof input === "string";
-const ImageLinkKind = new t.Type("ImageLinkKind", (input) => isImageLinkKind(input), (input, context) => isImageLinkKind(input)
-    ? t.success("image")
-    : t.failure(input, context), () => "image");
 const filledImageLinkLegacyCodec = t.intersection([
     t.strict({
-        kind: ImageLinkKind,
+        kind: t.string,
         id: t.string,
         url: t.string,
         height: t.string,
@@ -73,13 +92,9 @@ exports.ImageLinkContent = t.intersection([
 ]);
 // FileLink.
 exports.FileLinkType = "FileLink";
-const isFileLinkKind = (input) => typeof input === "string";
-const FileLinkKind = new t.Type("FileLinkKind", (input) => isFileLinkKind(input), (input, context) => isFileLinkKind(input)
-    ? t.success("file")
-    : t.failure(input, context), () => "file");
 const filledFileLinkLegacyCodec = t.exact(t.intersection([
     t.type({
-        kind: FileLinkKind,
+        kind: t.string,
         id: t.string,
         url: t.string,
         name: t.string,