datocms-plugin-sdk 2.0.4 → 2.0.6

package/src/hooks/customBlockStylesForStructuredTextField.ts

@@ -1,6 +1,13 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { BlockNodeTypeWithCustomStyle } from 'datocms-structured-text-utils';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 type Field = SchemaTypes.Field;
 type ItemType = SchemaTypes.ItemType;
@@ -22,7 +29,11 @@ export type CustomBlockStylesForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 
-/** An object expressing a custom block style for a Structured Text field */
+/**
+ * An object expressing a custom block style for a Structured Text field
+ *
+ * @see {isStructuredTextCustomBlockStyle}
+ */
 export type StructuredTextCustomBlockStyle = {
   /** ID of custom block style */
   id: string;
@@ -40,3 +51,21 @@ export type StructuredTextCustomBlockStyle = {
    */
   rank?: number;
 };
+
+export function isStructuredTextCustomBlockStyle(
+  value: unknown,
+): value is StructuredTextCustomBlockStyle {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    isString(value.node) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}
+
+export function isReturnTypeOfCustomBlockStylesForStructuredTextFieldHook(
+  value: unknown,
+): value is StructuredTextCustomBlockStyle[] | undefined {
+  return isNullish(value) || isArray(value, isStructuredTextCustomBlockStyle);
+}

package/src/hooks/customMarksForStructuredTextField.ts

@@ -1,6 +1,14 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 type Field = SchemaTypes.Field;
 type ItemType = SchemaTypes.ItemType;
@@ -22,7 +30,11 @@ export type CustomMarksForStructuredTextFieldCtx = Ctx<{
   itemType: ItemType;
 }>;
 
-/** An object expressing a custom mark for a Structured Text field */
+/**
+ * An object expressing a custom mark for a Structured Text field
+ *
+ * @see {isStructuredTextCustomMark}
+ */
 export type StructuredTextCustomMark = {
   /** ID of mark */
   id: string;
@@ -62,3 +74,24 @@ export type StructuredTextCustomMarkPlacement = [
   'before' | 'after',
   'strong' | 'emphasis' | 'underline' | 'code' | 'highlight' | 'strikethrough',
 ];
+
+export function isStructuredTextCustomMark(
+  value: unknown,
+): value is StructuredTextCustomMark {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.keyboardShortcut) || isString(value.keyboardShortcut)) &&
+    isRecord(value.appliedStyle)
+  );
+}
+
+export function isReturnTypeOfCustomMarksForStructuredTextFieldHook(
+  value: unknown,
+): value is StructuredTextCustomMark[] | undefined {
+  return isNullish(value) || isArray(value, isStructuredTextCustomMark);
+}

package/src/hooks/initialLocationQueryForItemSelector.ts

@@ -1,6 +1,6 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx, ItemListLocationQuery } from '../ctx/base';
-
+import { isNullish, isNumber, isRecord } from '../guardUtils.js';
 import { MaybePromise } from '../utils';
 
 type Field = SchemaTypes.Field;
@@ -22,6 +22,11 @@ export type InitialLocationQueryForItemSelectorHook = {
 
 export type InitialLocationQueryForItemSelectorCtx = Ctx;
 
+/**
+ * An object expressing which filters should be applied to the record selector
+ *
+ * @see {isInitialLocationQueryForItemSelector}
+ */
 export type InitialLocationQueryForItemSelector = {
   locationQuery: ItemListLocationQuery;
   /**
@@ -33,3 +38,19 @@ export type InitialLocationQueryForItemSelector = {
    */
   rank?: number;
 };
+
+export function isInitialLocationQueryForItemSelector(
+  value: unknown,
+): value is InitialLocationQueryForItemSelector {
+  return (
+    isRecord(value) &&
+    isRecord(value.locationQuery) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}
+
+export function isReturnTypeOfInitialLocationQueryForItemSelectorHook(
+  value: unknown,
+): value is InitialLocationQueryForItemSelector | undefined {
+  return isNullish(value) || isInitialLocationQueryForItemSelector(value);
+}

package/src/hooks/itemCollectionOutlets.ts

@@ -1,5 +1,12 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,7 +25,11 @@ export type ItemCollectionOutletsHook = {
 
 export type ItemCollectionOutletsCtx = Ctx;
 
-/** An outlet to be shown at the top of a record's collection page */
+/**
+ * An object expressing an outlet to be shown at the top of a record's collection page
+ *
+ * @see {isItemCollectionOutlet}
+ */
 export type ItemCollectionOutlet = {
   /**
    * ID of the outlet. Will be the first argument for the `renderItemCollectionOutlet`
@@ -35,3 +46,20 @@ export type ItemCollectionOutlet = {
   /** The initial height to set for the iframe that will render the outlet */
   initialHeight?: number;
 };
+
+export function isItemCollectionOutlet(
+  value: unknown,
+): value is ItemCollectionOutlet {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfItemCollectionOutletsHook(
+  value: unknown,
+): value is ItemCollectionOutlet[] {
+  return isArray(value, isItemCollectionOutlet);
+}

package/src/hooks/itemFormOutlets.ts

@@ -1,5 +1,12 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,6 +25,11 @@ export type ItemFormOutletsHook = {
 
 export type ItemFormOutletsCtx = Ctx;
 
+/**
+ * An object expressing an outlet to be shown at the top of a record's editing page
+ *
+ * @see {isItemFormOutlet}
+ */
 export type ItemFormOutlet = {
   /**
    * ID of the outlet. Will be the first argument for the `renderItemFormOutlet`
@@ -34,3 +46,18 @@ export type ItemFormOutlet = {
   /** The initial height to set for the iframe that will render the outlet */
   initialHeight?: number;
 };
+
+export function isItemFormOutlet(value: unknown): value is ItemFormOutlet {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfItemFormOutletsHook(
+  value: unknown,
+): value is ItemFormOutlet[] {
+  return isArray(value, isItemFormOutlet);
+}

package/src/hooks/itemFormSidebarPanels.ts

@@ -1,5 +1,14 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 import { ItemFormSidebarPanelPlacement } from '../shared';
 
 type ItemType = SchemaTypes.ItemType;
@@ -19,6 +28,12 @@ export type ItemFormSidebarPanelsHook = {
 
 export type ItemFormSidebarPanelsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar panel to be shown when the user
+ * edits records of a particular model
+ *
+ * @see {isItemFormSidebarPanel}
+ */
 export type ItemFormSidebarPanel = {
   /**
    * ID of the panel. Will be the first argument for the
@@ -52,3 +67,24 @@ export type ItemFormSidebarPanel = {
   /** The initial height to set for the iframe that will render the sidebar panel */
   initialHeight?: number;
 };
+
+export function isItemFormSidebarPanel(
+  value: unknown,
+): value is ItemFormSidebarPanel {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.startOpen) || isBoolean(value.startOpen)) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfItemFormSidebarPanelsHook(
+  value: unknown,
+): value is ItemFormSidebarPanel[] {
+  return isArray(value, isItemFormSidebarPanel);
+}

package/src/hooks/itemFormSidebars.ts

@@ -1,5 +1,12 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 type ItemType = SchemaTypes.ItemType;
 
@@ -18,6 +25,12 @@ export type ItemFormSidebarsHook = {
 
 export type ItemFormSidebarsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar to be shown when the user edits
+ * records of a particular model
+ *
+ * @see {isItemFormSidebar}
+ */
 export type ItemFormSidebar = {
   /**
    * ID of the sidebar. Will be the first argument for the
@@ -42,3 +55,20 @@ export type ItemFormSidebar = {
   /** The preferred width for the sidebar */
   preferredWidth?: number;
 };
+
+export function isItemFormSidebar(value: unknown): value is ItemFormSidebar {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.preferredWidth) || isNumber(value.preferredWidth))
+  );
+}
+
+export function isReturnTypeOfItemFormSidebarsHook(
+  value: unknown,
+): value is ItemFormSidebar[] {
+  return isArray(value, isItemFormSidebar);
+}

package/src/hooks/mainNavigationTabs.ts

@@ -1,5 +1,13 @@
 import { Ctx } from '../ctx/base';
-import { Icon } from '../icon';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
+import { Icon, isIcon } from '../icon';
 
 export type MainNavigationTabsHook = {
   /**
@@ -13,7 +21,11 @@ export type MainNavigationTabsHook = {
 
 export type MainNavigationTabsCtx = Ctx;
 
-/** A tab to be displayed in the top-bar of the UI */
+/**
+ * An object expressing a tab to be displayed in the top-bar of the UI
+ *
+ * @see {isMainNavigationTab}
+ */
 export type MainNavigationTab = {
   /** Label to be shown. Must be unique. */
   label: string;
@@ -45,3 +57,23 @@ export type MainNavigationTab = {
    */
   rank?: number;
 };
+
+export function isMainNavigationTab(
+  value: unknown,
+): value is MainNavigationTab {
+  return (
+    isRecord(value) &&
+    isString(value.label) &&
+    isIcon(value.icon) &&
+    isRecord(value.pointsTo) &&
+    isString(value.pointsTo.pageId) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank))
+  );
+}
+
+export function isReturnTypeOfMainNavigationTabsHook(
+  value: unknown,
+): value is MainNavigationTab[] {
+  return isArray(value, isMainNavigationTab);
+}

package/src/hooks/manualFieldExtensions.ts

@@ -1,4 +1,12 @@
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 export type ManualFieldExtensionsHook = {
   /**
@@ -14,6 +22,12 @@ export type ManualFieldExtensionsHook = {
 
 export type ManualFieldExtensionsCtx = Ctx;
 
+/**
+ * An object expressing a field extension that users will be able
+ * to install manually in some field
+ *
+ * @see {isManualFieldExtension}
+ */
 export type ManualFieldExtension = {
   /**
    * ID of field extension. Will be the first argument for the
@@ -80,3 +94,32 @@ export type FieldType =
   | 'structured_text'
   | 'text'
   | 'video';
+
+export function isManualFieldExtension(
+  value: unknown,
+): value is ManualFieldExtension {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.name) &&
+    isString(value.type) &&
+    ['editor', 'addon'].includes(value.type) &&
+    (isNullish(value.asSidebarPanel) ||
+      isBoolean(value.asSidebarPanel) ||
+      (isRecord(value.asSidebarPanel) &&
+        isBoolean(value.asSidebarPanel.startOpen))) &&
+    ((isString(value.fieldTypes) && value.fieldTypes === 'all') ||
+      isArray(value.fieldTypes, isString)) &&
+    (isNullish(value.configurable) ||
+      isBoolean(value.configurable) ||
+      (isRecord(value.configurable) &&
+        isNumber(value.configurable.initialHeight))) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfManualFieldExtensionsHook(
+  value: unknown,
+): value is ManualFieldExtension[] {
+  return isArray(value, isManualFieldExtension);
+}

package/src/hooks/overrideFieldExtensions.ts

@@ -1,5 +1,14 @@
 import type { SchemaTypes } from '@datocms/cma-client';
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 import { ItemFormSidebarPanelPlacement } from '../shared';
 
 type Field = SchemaTypes.Field;
@@ -25,6 +34,8 @@ export type OverrideFieldExtensionsCtx = Ctx<{
 /**
  * An object expressing some field extensions you want to force on a particular
  * field
+ *
+ * @see {isFieldExtensionOverride}
  */
 export type FieldExtensionOverride = {
   /** Force a field editor/sidebar extension on a field */
@@ -93,3 +104,47 @@ export type AddonOverride = {
    */
   initialHeight?: number;
 };
+
+export function isFieldExtensionOverride(
+  value: unknown,
+): value is FieldExtensionOverride {
+  return (
+    isNullish(value) ||
+    (isRecord(value) &&
+      (isNullish(value.editor) || isEditorOverride(value.editor)) &&
+      (isNullish(value.addons) || isArray(value.addons, isAddonOverride)))
+  );
+}
+
+export function isEditorOverride(value: unknown): value is EditorOverride {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.asSidebarPanel) ||
+      isBoolean(value.asSidebarPanel) ||
+      (isRecord(value.asSidebarPanel) &&
+        (isNullish(value.asSidebarPanel.startOpen) ||
+          isBoolean(value.asSidebarPanel.startOpen)) &&
+        (isNullish(value.asSidebarPanel.placement) ||
+          isPlacement(value.asSidebarPanel.placement)))) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isAddonOverride(value: unknown): value is AddonOverride {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfOverrideFieldExtensionsHook(
+  value: unknown,
+): value is FieldExtensionOverride | undefined {
+  return isNullish(value) || isFieldExtensionOverride(value);
+}

package/src/hooks/uploadSidebarPanels.ts

@@ -1,4 +1,13 @@
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isBoolean,
+  isNullish,
+  isNumber,
+  isPlacement,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 export type UploadSidebarPanelsHook = {
   /**
@@ -12,6 +21,12 @@ export type UploadSidebarPanelsHook = {
 
 export type UploadSidebarPanelsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar panel to be shown when the user
+ * opens up an asset in the Media Area
+ *
+ * @see {isUploadSidebarPanel}
+ */
 export type UploadSidebarPanel = {
   /**
    * ID of the panel. Will be the first argument for the
@@ -57,3 +72,24 @@ export type UploadSidebarPanelPlacement = [
     | 'replace'
   ),
 ];
+
+export function isUploadSidebarPanel(
+  value: unknown,
+): value is UploadSidebarPanel {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.startOpen) || isBoolean(value.startOpen)) &&
+    (isNullish(value.placement) || isPlacement(value.placement)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.initialHeight) || isNumber(value.initialHeight))
+  );
+}
+
+export function isReturnTypeOfUploadSidebarPanelsHook(
+  value: unknown,
+): value is UploadSidebarPanel[] {
+  return isArray(value, isUploadSidebarPanel);
+}

package/src/hooks/uploadSidebars.ts

@@ -1,4 +1,11 @@
 import { Ctx } from '../ctx/base';
+import {
+  isArray,
+  isNullish,
+  isNumber,
+  isRecord,
+  isString,
+} from '../guardUtils.js';
 
 export type UploadSidebarsHook = {
   /**
@@ -12,6 +19,12 @@ export type UploadSidebarsHook = {
 
 export type UploadSidebarsCtx = Ctx;
 
+/**
+ * An object expressing a sidebar to be shown when the user opens
+ * up an asset in the Media Area
+ *
+ * @see {isUploadSidebar}
+ */
 export type UploadSidebar = {
   /**
    * ID of the sidebar. Will be the first argument for the
@@ -36,3 +49,20 @@ export type UploadSidebar = {
   /** The preferred width for the sidebar */
   preferredWidth?: number;
 };
+
+export function isUploadSidebar(value: unknown): value is UploadSidebar {
+  return (
+    isRecord(value) &&
+    isString(value.id) &&
+    isString(value.label) &&
+    (isNullish(value.parameters) || isRecord(value.parameters)) &&
+    (isNullish(value.rank) || isNumber(value.rank)) &&
+    (isNullish(value.preferredWidth) || isNumber(value.preferredWidth))
+  );
+}
+
+export function isReturnTypeOfUploadSidebarsHook(
+  value: unknown,
+): value is UploadSidebar[] {
+  return isArray(value, isUploadSidebar);
+}

package/src/hooks/validateManualFieldExtensionParameters.ts

@@ -1,3 +1,5 @@
+import { isRecord } from '../guardUtils';
+
 export type ValidateManualFieldExtensionParametersHook = {
   /**
    * This function will be called each time the configuration object changes. It
@@ -10,3 +12,9 @@ export type ValidateManualFieldExtensionParametersHook = {
     parameters: Record<string, unknown>,
   ) => Record<string, unknown> | Promise<Record<string, unknown>>;
 };
+
+export function isReturnTypeOfValidateManualFieldExtensionParametersHook(
+  value: unknown,
+): value is Record<string, unknown> {
+  return isRecord(value);
+}

package/src/icon.ts

@@ -1,7 +1,19 @@
+import { isRecord, isString } from './guardUtils.js';
+
 export type Icon =
   | AwesomeFontIconIdentifier
   | { type: 'svg'; viewBox: string; content: string };
 
+export function isIcon(value: unknown): value is Icon {
+  return (
+    isString(value) ||
+    (isRecord(value) &&
+      value.type === 'svg' &&
+      isString(value.viewBox) &&
+      isString(value.content))
+  );
+}
+
 export type AwesomeFontIconIdentifier =
   | '0'
   | '00'