@dosgato/templating 0.0.28 → 0.0.31

package/dist/apitemplate.d.ts

@@ -1,4 +1,4 @@
-import { PageRecord, ComponentData, PageData } from './component.js';
+import { PageRecord, ComponentData, DataData, PageData } from './component.js';
 import { LinkDefinition } from './links.js';
 export declare type APITemplateType = 'page' | 'component' | 'data';
 export declare enum ValidationMessageType {
@@ -25,18 +25,6 @@ export interface APITemplate {
      * A uniquey human-readable name describing this template
      */
     name: string;
-    /**
-     * Each template must declare its areas and the template keys of components that will be
-     * permitted inside each area. The list of allowed component templates can be updated beyond
-     * the list provided here. See templateRegistry.addAvailableComponent's comment for info on why.
-     */
-    areas: Record<string, string[]>;
-    /**
-     * Each template must provide a list of migrations for upgrading the data schema over time.
-     * Typically this will start as an empty array and migrations will be added as the template
-     * gets refactored.
-     */
-    migrations: Migration[];
     /**
      * Each template must provide a function that returns links from its data so that they
      * can be indexed. Only fields that are links need to be returned. Links inside rich editor
@@ -49,6 +37,15 @@ export interface APITemplate {
      * by this function will also be scanned for links.
      */
     getFulltext: FulltextGatheringFn;
+}
+export interface APIComponentTemplate extends APITemplate {
+    type: 'component';
+    /**
+     * Each template must declare its areas and the template keys of components that will be
+     * permitted inside each area. The list of allowed component templates can be updated beyond
+     * the list provided here. See templateRegistry.addAvailableComponent's comment for info on why.
+     */
+    areas?: Record<string, string[]>;
     /**
      * Each template must provide a validation function so that the API can enforce its data is
      * shaped properly.
@@ -66,7 +63,25 @@ export interface APITemplate {
      * available as parameters in case you need them. Keep in mind that the current editor MUST
      * have access to any data you attempt to query in GraphQL.
      */
-    validate?: (data: ComponentData, query: <T>(query: string, variables?: any) => Promise<T>, page: PageData, path: string) => Promise<ValidationFeedback[]>;
+    validate?: (data: ComponentData, query: GraphQLQueryFn, page: PageRecord, path: string) => Promise<ValidationFeedback[]>;
+    /**
+     * Each template must provide a list of migrations for upgrading the data schema over time.
+     * Typically this will start as an empty array and migrations will be added as the template
+     * gets refactored.
+     */
+    migrations: ComponentMigration[];
+}
+export interface APIPageTemplate extends APITemplate {
+    type: 'page';
+    /**
+     * Page areas are the same as components but are required.
+     */
+    areas: Record<string, string[]>;
+    /**
+     * Page template implementations do not receive a path like component templates do.
+     */
+    validate?: (data: ComponentData, query: GraphQLQueryFn, page: PageRecord) => Promise<ValidationFeedback[]>;
+    migrations: PageMigration[];
     /**
      * Hard-coded properties that may be set on page templates to influence the rendering of
      * components on the page. For instance, a set of color choices that are customized for
@@ -78,6 +93,15 @@ export interface APITemplate {
      */
     templateProperties?: any;
 }
+export interface APIDataTemplate extends APITemplate {
+    type: 'data';
+    /**
+     * Data template implementations receive the dataId so they can self-reference in queries.
+     */
+    validate?: (data: ComponentData, query: GraphQLQueryFn, dataId: string) => Promise<ValidationFeedback[]>;
+    migrations: DataMigration[];
+}
+export declare type APIAnyTemplate = APIComponentTemplate | APIPageTemplate | APIDataTemplate;
 /**
  * In dosgato CMS, the data in the database is not altered except during user activity. This
  * means that older records could have been saved when the schema expected by component
@@ -97,14 +121,34 @@ export interface APITemplate {
  *
  * Your `up` and `down` methods will be applied to components in bottom-up fashion, so you
  * can assume that any components inside one of your areas has already been processed.
+ *
+ * All migration functions receive a `query` function for making a graphql query, in case the
+ * migration depends on the state of a parent page or something. Be careful not
+ * to create an infinite loop - querying a page will trigger that page to be migrated, which
+ * could end up calling your code again on that page.
+ *
+ * If you're migrating a component template, you'll also get the page record and the
+ * path inside that page's data to the component being migrated.
  */
 export interface Migration {
     createdAt: Date;
-    up: (data: ComponentData, page: PageRecord) => ComponentData | Promise<ComponentData>;
-    down: (data: ComponentData, page: PageRecord) => ComponentData | Promise<ComponentData>;
 }
+export interface ComponentMigration extends Migration {
+    up: (data: ComponentData, query: GraphQLQueryFn, page: PageRecord, path: string) => ComponentData | Promise<ComponentData>;
+    down: (data: ComponentData, query: GraphQLQueryFn, page: PageRecord, path: string) => ComponentData | Promise<ComponentData>;
+}
+export interface PageMigration extends Migration {
+    up: (data: PageData, query: GraphQLQueryFn, page: PageRecord) => PageData | Promise<PageData>;
+    down: (data: PageData, query: GraphQLQueryFn, page: PageRecord) => PageData | Promise<PageData>;
+}
+export interface DataMigration extends Migration {
+    up: (data: DataData, query: GraphQLQueryFn, dataId: string) => DataData | Promise<DataData>;
+    down: (data: DataData, query: GraphQLQueryFn, dataId: string) => DataData | Promise<DataData>;
+}
+export declare type AnyMigration = ComponentMigration | PageMigration | DataMigration;
 export declare type LinkGatheringFn = (data: any) => LinkDefinition[];
 export declare type FulltextGatheringFn = (data: any) => string[];
+export declare type GraphQLQueryFn = <T>(query: string, variables?: any) => Promise<T>;
 /**
  * This function is used by API template definitions to help them identify links inside large blocks
  * of text and return them for indexing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dosgato/templating",
-  "version": "0.0.28",
+  "version": "0.0.31",
   "description": "A library to support building templates for dosgato CMS.",
   "type": "module",
   "exports": {