@platecms/delta-cast 1.0.0 → 1.2.0

package/src/lib/schemas/schema.ts

@@ -0,0 +1,277 @@
+import { Node, Literal as UnistLiteral, Parent as UnistParent } from "unist";
+
+export type Content = BlockContent | CasSuggestion | InlineContent;
+
+export type BlockContent = BlockContentMap[keyof BlockContentMap];
+export type InlineContent = InlineContentMap[keyof InlineContentMap];
+
+export interface BlockContentMap {
+  paragraph: Paragraph;
+  heading: Heading;
+  list: List;
+  // List item should not be used anywhere except in the list's children
+  listItem: ListItem;
+  blockquote: Blockquote;
+  code: Code;
+}
+
+export interface InlineContentMap {
+  text: Text;
+  bold: Bold;
+  italic: Italic;
+  underline: Underline;
+  strikethrough: Strikethrough;
+  inlineCode: InlineCode;
+  highlight: Highlight;
+  contentValue: InterpolatedContentValue;
+  externalLink: ExternalLink;
+  internalLink: InternalLink;
+  casSuggestion: CasSuggestion;
+  contentValueSuggestion: ContentValueSuggestion;
+}
+
+export interface Parent extends UnistParent {
+  children: Content[];
+}
+
+export interface Literal extends UnistLiteral {
+  value: string;
+}
+
+/*
+ ** Specific CAST Definitions
+ */
+
+/**
+ * The root node of a CAST document. The unist tree starts here. Each CAST document has one root node.
+ *
+ * ```json
+ * {
+ *   "type": "root",
+ *   "children": [
+ *     ...
+ *   ]
+ * }
+ */
+export interface Root extends Parent {
+  type: "root";
+}
+
+/*
+ ** Block Content
+ */
+export interface Paragraph extends Parent {
+  type: "paragraph";
+
+  /**
+   * The children of a paragraph are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Heading extends Parent {
+  type: "heading";
+
+  /**
+   * The level of a heading is a number between 1 and 6.
+   */
+  level: 1 | 2 | 3 | 4 | 5 | 6;
+
+  /**
+   * The children of a heading are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface List extends Parent {
+  type: "list";
+
+  children: ListItem[];
+
+  /**
+   * Whether the list is ordered or not.
+   */
+  ordered: boolean;
+
+  /**
+   * The start of an ordered list.
+   */
+  start?: number;
+}
+
+export interface ListItem extends Parent {
+  type: "listItem";
+
+  /**
+   * The children of a list item are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Blockquote extends Parent {
+  type: "blockquote";
+
+  /**
+   * The children of a blockquote are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Code extends Parent {
+  type: "code";
+
+  /**
+   * The language of the code block.
+   */
+  lang?: string;
+
+  children: Text[];
+}
+
+/*
+ ** Inline Content
+ */
+export interface Text extends Literal {
+  type: "text";
+}
+
+export interface Bold extends Parent {
+  type: "bold";
+
+  /**
+   * The children of a bold node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Italic extends Parent {
+  type: "italic";
+
+  /**
+   * The children of an italic node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Underline extends Parent {
+  type: "underline";
+
+  /**
+   * The children of an underline node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface Strikethrough extends Parent {
+  type: "strikethrough";
+
+  /**
+   * The children of a strikethrough node are inline content.
+   */
+  children: InlineContent[];
+}
+
+export interface InlineCode extends Literal {
+  type: "inlineCode";
+}
+
+export interface Highlight extends Parent {
+  type: "highlight";
+
+  /**
+   * The children of a highlight node are inline content
+   */
+  children: InlineContent[];
+}
+
+/**
+ * Represents an interpolated Content Value. Interpolated values are values that are stored elsewhere in the database
+ * and inserted into the document at request-time.
+ */
+export interface InterpolatedContentValue extends Node {
+  type: "contentValue";
+
+  /**
+   * The PRN (identifier) of the referenced Content Value.
+   */
+  prn: string;
+
+  /**
+   * The nested CAST tree of the referenced Content Value.
+   */
+  value?: Root;
+}
+
+export interface ContentValueSuggestion extends Node {
+  type: "contentValueSuggestion";
+
+  /**
+   * The PRN (identifier) of the referenced Content Value.
+   */
+  prn: string;
+
+  /**
+   * The nested CAST tree of the referenced Content Value.
+   */
+  value?: Root;
+}
+
+export interface ExternalLink extends Parent {
+  type: "externalLink";
+
+  children: Text[];
+
+  /**
+   * The URL of the link.
+   */
+  url: string;
+
+  target?: "_parent" | "_top" | "blank" | "self";
+}
+
+export interface InternalLink extends Parent {
+  type: "internalLink";
+
+  children: Text[];
+
+  /**
+   * The PRN (identifier) of the referenced Path Part or Grid Placement.
+   */
+  prn: string;
+
+  /**
+   * The URL of the link. Consists of the channel and the path part. Optionally includes a grid placement reference (e.g. #anchor-name).
+   * Even though the URL is marked as optional, it is always defined when retrieving an internal link.
+   * It is not required when saving an internal link.
+   */
+  url?: string;
+
+  target?: "_parent" | "_top" | "blank" | "self";
+}
+
+/**
+ * A CAS suggestion node.
+ */
+export interface CasSuggestion extends Node {
+  type: "casSuggestion";
+
+  /**
+   * The original content that is suggested to be replaced.
+   */
+  original: Content[];
+
+  /**
+   * The suggested replacement content.
+   */
+  suggested: Content[];
+
+  /**
+   * A message explaining the suggestion.
+   */
+  message: string;
+
+  /**
+   * The method or algorithm that created the suggestion (e.g. "database; reusable")
+   */
+  method: string;
+}

package/src/lib/validate-cast.spec.ts

@@ -0,0 +1,395 @@
+import { validateCast } from "./validate-cast";
+import {
+  Blockquote,
+  Bold,
+  CasSuggestion,
+  Code,
+  Content,
+  ExternalLink,
+  Heading,
+  Highlight,
+  InlineCode,
+  InlineContent,
+  InternalLink,
+  InterpolatedContentValue,
+  Italic,
+  List,
+  ListItem,
+  Paragraph,
+  Root,
+  Strikethrough,
+  Text,
+  Underline,
+} from "./schemas/schema";
+import { InvalidCastError } from "./invalid-cast.error";
+
+describe("validateCast", () => {
+  describe("validates correct CAST trees successfully", () => {
+    it.each([
+      [
+        "valid paragraph",
+        { type: "paragraph", children: [{ type: "text", value: "Hello, world!" }] } satisfies Paragraph,
+      ],
+      [
+        "valid heading",
+        { type: "heading", level: 1, children: [{ type: "text", value: "Heading" }] } satisfies Heading,
+      ],
+      [
+        "valid list",
+        {
+          type: "list",
+          children: [{ type: "listItem", children: [{ type: "text", value: "Item" }] }],
+          ordered: false,
+        } satisfies List,
+      ],
+      [
+        "valid code block",
+        {
+          type: "code",
+          lang: "javascript",
+          children: [{ type: "text", value: "console.log('Hello, world!');" }],
+        } satisfies Code,
+      ],
+      [
+        "valid interpolated content value",
+        { type: "contentValue", prn: "prn:plate-dev:1234:cms:test:abcd" } satisfies InterpolatedContentValue,
+      ],
+      [
+        "valid external link",
+        {
+          type: "externalLink",
+          url: "https://www.google.com",
+          children: [{ type: "text", value: "External link" }],
+        } satisfies ExternalLink,
+      ],
+      [
+        "valid internal link",
+        {
+          type: "internalLink",
+          url: "https://www.hotet.getplate.rocks/blogs",
+          prn: "prn:plate-dev:1234:cms:test:abcd",
+          children: [{ type: "text", value: "Internal link" }],
+        } satisfies InternalLink,
+      ],
+      [
+        "valid internal link with anchor",
+        {
+          type: "internalLink",
+          url: "https://www.hotet.getplate.rocks/blogs#123",
+          prn: "prn:plate-dev:1234:cms:test:abcd",
+          children: [{ type: "text", value: "Internal link" }],
+        } satisfies InternalLink,
+      ],
+      ["valid text", { type: "text", value: "Hello, world!" } satisfies Text],
+      ["valid bold", { type: "bold", children: [{ type: "text", value: "Bold text" }] } satisfies Bold],
+      ["valid italic", { type: "italic", children: [{ type: "text", value: "Italic text" }] } satisfies Italic],
+      [
+        "valid underline",
+        { type: "underline", children: [{ type: "text", value: "Underline text" }] } satisfies Underline,
+      ],
+      [
+        "valid strikethrough",
+        { type: "strikethrough", children: [{ type: "text", value: "Strikethrough text" }] } satisfies Strikethrough,
+      ],
+      ["valid inline code", { type: "inlineCode", value: "code" } satisfies InlineCode],
+      [
+        "valid highlight",
+        { type: "highlight", children: [{ type: "text", value: "Highlight text" }] } satisfies Highlight,
+      ],
+      [
+        "valid blockquote",
+        { type: "blockquote", children: [{ type: "text", value: "Blockquote text" }] } satisfies Blockquote,
+      ],
+      [
+        "valid cas suggestion",
+        {
+          type: "casSuggestion",
+          original: [{ type: "text", value: "Original text" }],
+          suggested: [{ type: "text", value: "Suggested text" }],
+          message: "This is a suggestion",
+          method: "database; reusable",
+        } satisfies CasSuggestion,
+      ],
+    ])("validates a %s", (_, input) => {
+      const root: Root = { type: "root", children: [input as Content] };
+      expect(() => validateCast(root)).not.toThrow();
+    });
+  });
+
+  describe("validates incorrect CAST trees successfully", () => {
+    it.each([
+      ["root not an object", { type: "root", children: null } as unknown as Root],
+      ["root type not 'root'", { type: "notRoot", children: [] } as unknown as Root],
+      ["root children array has null", { type: "root", children: [null] }],
+      ["root children not an array", { type: "root", children: "notAnArray" } as unknown as Root],
+      ["invalid Content type", { type: "root", children: [{ type: "invalid" }] } as unknown as Root],
+      [
+        "invalid paragraph",
+        {
+          type: "root",
+          children: [{ type: "paragraph", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid heading",
+        {
+          type: "root",
+          children: [
+            {
+              type: "heading",
+              level: "one" as unknown as 1,
+              children: [{ type: "text", value: "Invalid heading level" }],
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid list",
+        {
+          type: "root",
+          children: [
+            {
+              type: "list",
+              ordered: false,
+              children: [{ type: "listItem", children: null as unknown as InlineContent[] }],
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid code block",
+        {
+          type: "root",
+          children: [
+            { type: "code", lang: 123 as unknown as string, children: [{ type: "text", value: "// my code" }] },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid interpolated content value",
+        { type: "root", children: [{ type: "contentValue", prn: "invalid-prn" }] } satisfies Root,
+      ],
+      [
+        "invalid external link",
+        {
+          type: "root",
+          children: [{ type: "externalLink", url: "invalid-url", children: null as unknown as Text[] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid internal link",
+        {
+          type: "root",
+          children: [
+            {
+              type: "internalLink",
+              url: "invalid-url",
+              children: null as unknown as Text[],
+              prn: "invalid-prn",
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid internal anchor link",
+        {
+          type: "root",
+          children: [
+            {
+              type: "internalLink",
+              url: "invalid-url",
+              children: null as unknown as Text[],
+              prn: "invalid-prn",
+            },
+          ],
+        } satisfies Root,
+      ],
+      ["invalid text", { type: "root", children: [{ type: "text", value: null as unknown as string }] } satisfies Root],
+      [
+        "invalid bold",
+        {
+          type: "root",
+          children: [{ type: "bold", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid italic",
+        {
+          type: "root",
+          children: [{ type: "italic", children: [{ type: "text", value: undefined as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid underline",
+        {
+          type: "root",
+          children: [{ type: "underline", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid strikethrough",
+        {
+          type: "root",
+          children: [{ type: "strikethrough", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid inline code",
+        { type: "root", children: [{ type: "inlineCode", value: null as unknown as string }] } satisfies Root,
+      ],
+      [
+        "invalid highlight",
+        {
+          type: "root",
+          children: [{ type: "highlight", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid blockquote",
+        {
+          type: "root",
+          children: [{ type: "blockquote", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid list item",
+        {
+          type: "root",
+          children: [{ type: "listItem", children: [{ type: "text", value: null as unknown as string }] }],
+        } satisfies Root,
+      ],
+      [
+        "paragraph children not an array",
+        {
+          type: "root",
+          children: [{ type: "paragraph", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "heading children not an array",
+        {
+          type: "root",
+          children: [{ type: "heading", level: 1, children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "list children not an array",
+        {
+          type: "root",
+          children: [{ type: "list", ordered: true, children: "notAnArray" as unknown as ListItem[] }],
+        } satisfies Root,
+      ],
+      [
+        "bold children not an array",
+        {
+          type: "root",
+          children: [{ type: "bold", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "italic children not an array",
+        {
+          type: "root",
+          children: [{ type: "italic", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "underline children not an array",
+        {
+          type: "root",
+          children: [{ type: "underline", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "strikethrough children not an array",
+        {
+          type: "root",
+          children: [{ type: "strikethrough", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "highlight children not an array",
+        {
+          type: "root",
+          children: [{ type: "highlight", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "blockquote children not an array",
+        {
+          type: "root",
+          children: [{ type: "blockquote", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "listItem children not an array",
+        {
+          type: "root",
+          children: [{ type: "listItem", children: "notAnArray" as unknown as InlineContent[] }],
+        } satisfies Root,
+      ],
+      [
+        "invalid cas suggestion - original not an array",
+        {
+          type: "root",
+          children: [
+            {
+              type: "casSuggestion",
+              original: "notAnArray" as unknown as InlineContent[],
+              suggested: [{ type: "text", value: "Suggested text" }],
+              message: "This is a suggestion",
+              method: "database; reusable",
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid cas suggestion - suggested not an array",
+        {
+          type: "root",
+          children: [
+            {
+              type: "casSuggestion",
+              original: [{ type: "text", value: "Original text" }],
+              suggested: "notAnArray" as unknown as InlineContent[],
+              message: "This is a suggestion",
+              method: "database; reusable",
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid cas suggestion - message not a string",
+        {
+          type: "root",
+          children: [
+            {
+              type: "casSuggestion",
+              original: [{ type: "text", value: "Original text" }],
+              suggested: [{ type: "text", value: "Suggested text" }],
+              message: null as unknown as string,
+              method: "database; reusable",
+            },
+          ],
+        } satisfies Root,
+      ],
+      [
+        "invalid cas suggestion - method not a string",
+        {
+          type: "root",
+          children: [
+            {
+              type: "casSuggestion",
+              original: [{ type: "text", value: "Original text" }],
+              suggested: [{ type: "text", value: "Suggested text" }],
+              message: "This is a suggestion",
+              method: 123 as unknown as string,
+            },
+          ],
+        } satisfies Root,
+      ],
+    ])("throws an error for %s", (_, input) => {
+      expect(() => validateCast(input)).toThrow(InvalidCastError);
+    });
+  });
+});