@stackbit/types - npm Package Compare versions

Comparing version 0.6.0-staging.0 to 0.6.0-staging.1

dist/config-delegate.d.ts

@@ -6,3 +6,3 @@ import type { ModelWithSource } from './models';
     /**
-     * Finds a document by ID.
+     * Returns a {@link import('./content-source-document').Document} by ID.
      *
@@ -26,3 +26,3 @@ * If only one document with the provided `id` was found among all the content
     /**
-     * Finds a model by name.
+     * Return a {@link Model} by name.
      *
@@ -46,3 +46,3 @@ * If only one model with the provided `modelName` was found among all the
     /**
-     * Get the default locale of a content source.
+     * Returns the default locale of a content source.
      *
@@ -49,0 +49,0 @@ * @param options

dist/config.d.ts

@@ -1,2 +0,2 @@
-import type { ContentSourceInterface } from './content-source';
+import type { ContentSourceInterface, User } from './content-source';
 import type { DocumentWithSource } from './content-source-document';
@@ -6,2 +6,3 @@ import type { ModelExtension, ModelMatchFields, ModelWithSource, NamelessModelMap } from './models';
 import { SidebarButton } from './sidebar-button';
+import { ConfigDelegate } from './config-delegate';
 import { AssetSource } from './asset-source';
@@ -69,2 +70,3 @@ export interface StackbitConfig {
     }) => ModelWithSource[];
+    modelExtensions?: ModelExtension[];
     mapDocuments?: (options: {
@@ -74,3 +76,6 @@ documents: DocumentWithSource[];
     }) => DocumentWithSource[];
-    modelExtensions?: ModelExtension[];
+    onDocumentCreate?: (options: OnDocumentCreateOptions) => ReturnType<ContentSourceInterface['createDocument']>;
+    onDocumentUpdate?: (options: OnDocumentUpdateOptions) => ReturnType<ContentSourceInterface['updateDocument']>;
+    onDocumentDelete?: (options: OnDocumentDeleteOptions) => ReturnType<ContentSourceInterface['deleteDocument']>;
+    onPublishDocuments?: (options: OnDocumentsPublishOptions) => ReturnType<ContentSourceInterface['publishDocuments']>;
     /** @deprecated */
@@ -201,2 +206,122 @@ models?: NamelessModelMap;
 }
+export interface OnDocumentCreateOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `createDocument`
+     * method to create a document. You can transform this object and pass the
+     * result to the `createDocument` parameter to create a different document.
+     */
+    createDocumentOptions: Parameters<ContentSourceInterface['createDocument']>[0];
+    /**
+     * This function creates a document. Pass the `createDocumentOptions`
+     * parameter to this function to create a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    createDocument: (options?: Parameters<ContentSourceInterface['createDocument']>[0]) => ReturnType<ContentSourceInterface['createDocument']>;
+}
+export interface OnDocumentUpdateOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `updateDocument`
+     * method to update a document. You can transform this object and pass the
+     * result to the `updateDocument` parameter to update the document in a
+     * different way.
+     */
+    updateDocumentOptions: Parameters<ContentSourceInterface['updateDocument']>[0];
+    /**
+     * This function updates a document. Pass the `updateDocumentOptions`
+     * parameter to this function to update a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    updateDocument: (options?: Parameters<ContentSourceInterface['updateDocument']>[0]) => ReturnType<ContentSourceInterface['updateDocument']>;
+}
+export interface OnDocumentDeleteOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `deleteDocument`
+     * method to delete a document.
+     */
+    deleteDocumentOptions: Parameters<ContentSourceInterface['deleteDocument']>[0];
+    /**
+     * This function deletes a document. Pass the `deleteDocumentOptions`
+     * parameter to this function to delete a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    deleteDocument: (options?: Parameters<ContentSourceInterface['deleteDocument']>[0]) => ReturnType<ContentSourceInterface['deleteDocument']>;
+}
+export interface OnDocumentsPublishOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `publishDocuments`
+     * method to publish documents.
+     */
+    publishDocumentsOptions: Parameters<ContentSourceInterface['publishDocuments']>[0];
+    /**
+     * This function publishes documents. Pass the `publishDocumentsOptions`
+     * parameter to this function to publish documents.
+     */
+    publishDocuments: (options?: Parameters<ContentSourceInterface['publishDocuments']>[0]) => ReturnType<ContentSourceInterface['publishDocuments']>;
+}
+export interface DocumentHookBaseOptions extends ConfigDelegate {
+    /**
+     * The content source type of the current document
+     */
+    srcType: string;
+    /**
+     * The content source project ID of the current document
+     */
+    srcProjectId: string;
+    /**
+     * This object contains functions to create, update, delete and publish
+     * documents in the content source of the current document.
+     *
+     * All functions receive an optional `userContext`. If the `userContext`
+     * is not specified, a default `userContext` for the current user and the
+     * content source will be used.
+     *
+     * Calling these functions will trigger onDocument hooks. Therefore, do not
+     * use these function to create, update, delete and publish the current
+     * document, otherwise you will introduce an infinite loop.
+     */
+    contentSourceActions: ContentSourceActions;
+    /**
+     * This function returns an object containing functions to create, update,
+     * delete and publish documents in the content source matching the received
+     * `srType` and `srcProjectId`.
+     *
+     * The `srcProjectId` is optional. However, if there are multiple
+     * content source instances of the `srcType`, `undefined` will be returned
+     *
+     * All functions receive an optional `userContext`. If the `userContext`
+     * is not specified, a default `userContext` for the current user and the
+     * content source will be used.
+     *
+     * Calling these functions will trigger onDocument hooks. Therefore, do not
+     * use these function to create, update, delete and publish the current
+     * document, otherwise you will introduce an infinite loop.
+     *
+     * @param options
+     * @param {string} options.srcType The content source type
+     * @param {string} [options.srcProjectId] The content source project ID
+     */
+    getContentSourceActionsForSource: (options: {
+        srcType: string;
+        srcProjectId?: string;
+    }) => ContentSourceActions | undefined;
+    /**
+     * Returns the `userContext` of the current user for the content source
+     * specified by `srType`.
+     *
+     * The `userContext` can be used to create, update, delete and publish
+     * documents on behalf of the current user.
+     *
+     * Generally you don't need to pass the `userContext` yourself as it will be
+     * added automatically.
+     *
+     * @param {string} srcType The content source type
+     */
+    getUserContextForContentSourceType: (srcType: string) => User | undefined;
+}
+export interface ContentSourceActions {
+    createDocument: (...args: Parameters<ContentSourceInterface['createDocument']>) => ReturnType<ContentSourceInterface['createDocument']>;
+    updateDocument: (...args: Parameters<ContentSourceInterface['updateDocument']>) => ReturnType<ContentSourceInterface['updateDocument']>;
+    deleteDocument: (...args: Parameters<ContentSourceInterface['deleteDocument']>) => ReturnType<ContentSourceInterface['deleteDocument']>;
+    publishDocuments: (...args: Parameters<ContentSourceInterface['publishDocuments']>) => ReturnType<ContentSourceInterface['publishDocuments']>;
+}
 //# sourceMappingURL=config.d.ts.map

dist/content-source-operation.d.ts

@@ -1,2 +0,2 @@
-import type { Field, FieldType } from './model-fields';
+import type { Field, FieldListItems, FieldType } from './model-fields';
 export declare type UpdateOperation = UpdateOperationSet | UpdateOperationUnset | UpdateOperationInsert | UpdateOperationRemove | UpdateOperationReorder;
@@ -6,3 +6,3 @@ export interface UpdateOperationBase {
     fieldPath: (string | number)[];
-    modelField: Field;
+    modelField: Field | FieldListItems;
     locale?: string;
@@ -9,0 +9,0 @@ }

dist/content-source.d.ts

@@ -276,3 +276,3 @@ /// <reference types="node" />
     hasAccess(options: {
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<{
@@ -305,3 +305,3 @@ hasConnection: boolean;
         defaultLocaleDocumentId?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<{
@@ -329,3 +329,3 @@ documentId: string;
         operations: UpdateOperation[];
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<void>;
@@ -348,3 +348,3 @@ /**
         document: Document<DocumentContext>;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<void>;
@@ -375,3 +375,3 @@ /**
         locale?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<Asset<AssetContext>>;
@@ -387,3 +387,3 @@ /**
         locale?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<{
@@ -411,3 +411,3 @@ errors: ValidationError[];
         assets: Asset<AssetContext>[];
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<void>;
@@ -480,2 +480,6 @@ }
 }
+export declare type User<UserContext = unknown> = {
+    name: string;
+    email: string;
+} & UserContext;
 export declare type UserCommandSpawner = (options: SpawnUserCommandOptions) => ChildProcessWithoutNullStreams;
@@ -482,0 +486,0 @@ export interface SpawnUserCommandOptions {

package.json

 {
   "name": "@stackbit/types",
-  "version": "0.6.0-staging.0",
+  "version": "0.6.0-staging.1",
   "description": "Types for Stackbit config and Content Source Interface",
@@ -42,3 +42,3 @@ "main": "dist/index.js",
   },
-  "gitHead": "b9364b16f8be9f361d77cb304123762fd75683f5"
+  "gitHead": "59a544065749135aa992d5f9d39c88b14c3383dd"
 }

src/config-delegate.ts

@@ -7,3 +7,3 @@ import type { ModelWithSource } from './models';
     /**
-     * Finds a document by ID.
+     * Returns a {@link import('./content-source-document').Document} by ID.
      *
@@ -28,3 +28,3 @@ * If only one document with the provided `id` was found among all the content
     /**
-     * Finds a model by name.
+     * Return a {@link Model} by name.
      *
@@ -49,3 +49,3 @@ * If only one model with the provided `modelName` was found among all the
     /**
-     * Get the default locale of a content source.
+     * Returns the default locale of a content source.
      *
@@ -52,0 +52,0 @@ * @param options

src/config.ts

@@ -1,2 +0,2 @@
-import type { ContentSourceInterface } from './content-source';
+import type { ContentSourceInterface, User } from './content-source';
 import type { DocumentWithSource } from './content-source-document';
@@ -6,2 +6,3 @@ import type { ModelExtension, ModelMatchFields, ModelWithSource, NamelessModelMap } from './models';
 import { SidebarButton } from './sidebar-button';
+import { ConfigDelegate } from './config-delegate';
 import { AssetSource } from './asset-source';
@@ -78,5 +79,11 @@
     mapModels?: (options: { models: ModelWithSource[] }) => ModelWithSource[];
-    mapDocuments?: (options: { documents: DocumentWithSource[]; models: ModelWithSource[] }) => DocumentWithSource[];
     modelExtensions?: ModelExtension[];
 
+    // Document hooks
+    mapDocuments?: (options: { documents: DocumentWithSource[]; models: ModelWithSource[] }) => DocumentWithSource[];
+    onDocumentCreate?: (options: OnDocumentCreateOptions) => ReturnType<ContentSourceInterface['createDocument']>;
+    onDocumentUpdate?: (options: OnDocumentUpdateOptions) => ReturnType<ContentSourceInterface['updateDocument']>;
+    onDocumentDelete?: (options: OnDocumentDeleteOptions) => ReturnType<ContentSourceInterface['deleteDocument']>;
+    onPublishDocuments?: (options: OnDocumentsPublishOptions) => ReturnType<ContentSourceInterface['publishDocuments']>;
+
     /** @deprecated */
@@ -225,1 +232,143 @@ models?: NamelessModelMap;
 }
+
+export interface OnDocumentCreateOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `createDocument`
+     * method to create a document. You can transform this object and pass the
+     * result to the `createDocument` parameter to create a different document.
+     */
+    createDocumentOptions: Parameters<ContentSourceInterface['createDocument']>[0];
+    /**
+     * This function creates a document. Pass the `createDocumentOptions`
+     * parameter to this function to create a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    createDocument: (
+        options?: Parameters<ContentSourceInterface['createDocument']>[0]
+    ) => ReturnType<ContentSourceInterface['createDocument']>;
+}
+
+export interface OnDocumentUpdateOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `updateDocument`
+     * method to update a document. You can transform this object and pass the
+     * result to the `updateDocument` parameter to update the document in a
+     * different way.
+     */
+    updateDocumentOptions: Parameters<ContentSourceInterface['updateDocument']>[0];
+    /**
+     * This function updates a document. Pass the `updateDocumentOptions`
+     * parameter to this function to update a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    updateDocument: (
+        options?: Parameters<ContentSourceInterface['updateDocument']>[0]
+    ) => ReturnType<ContentSourceInterface['updateDocument']>;
+}
+
+export interface OnDocumentDeleteOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `deleteDocument`
+     * method to delete a document.
+     */
+    deleteDocumentOptions: Parameters<ContentSourceInterface['deleteDocument']>[0];
+    /**
+     * This function deletes a document. Pass the `deleteDocumentOptions`
+     * parameter to this function to delete a document. If you call this
+     * function without passing any options, original options will be used.
+     */
+    deleteDocument: (
+        options?: Parameters<ContentSourceInterface['deleteDocument']>[0]
+    ) => ReturnType<ContentSourceInterface['deleteDocument']>;
+}
+
+export interface OnDocumentsPublishOptions extends DocumentHookBaseOptions {
+    /**
+     * The `options` object is passed to the content source `publishDocuments`
+     * method to publish documents.
+     */
+    publishDocumentsOptions: Parameters<ContentSourceInterface['publishDocuments']>[0];
+    /**
+     * This function publishes documents. Pass the `publishDocumentsOptions`
+     * parameter to this function to publish documents.
+     */
+    publishDocuments: (
+        options?: Parameters<ContentSourceInterface['publishDocuments']>[0]
+    ) => ReturnType<ContentSourceInterface['publishDocuments']>;
+}
+
+export interface DocumentHookBaseOptions extends ConfigDelegate {
+    /**
+     * The content source type of the current document
+     */
+    srcType: string;
+    /**
+     * The content source project ID of the current document
+     */
+    srcProjectId: string;
+    /**
+     * This object contains functions to create, update, delete and publish
+     * documents in the content source of the current document.
+     *
+     * All functions receive an optional `userContext`. If the `userContext`
+     * is not specified, a default `userContext` for the current user and the
+     * content source will be used.
+     *
+     * Calling these functions will trigger onDocument hooks. Therefore, do not
+     * use these function to create, update, delete and publish the current
+     * document, otherwise you will introduce an infinite loop.
+     */
+    contentSourceActions: ContentSourceActions;
+    /**
+     * This function returns an object containing functions to create, update,
+     * delete and publish documents in the content source matching the received
+     * `srType` and `srcProjectId`.
+     *
+     * The `srcProjectId` is optional. However, if there are multiple
+     * content source instances of the `srcType`, `undefined` will be returned
+     *
+     * All functions receive an optional `userContext`. If the `userContext`
+     * is not specified, a default `userContext` for the current user and the
+     * content source will be used.
+     *
+     * Calling these functions will trigger onDocument hooks. Therefore, do not
+     * use these function to create, update, delete and publish the current
+     * document, otherwise you will introduce an infinite loop.
+     *
+     * @param options
+     * @param {string} options.srcType The content source type
+     * @param {string} [options.srcProjectId] The content source project ID
+     */
+    getContentSourceActionsForSource: (options: {
+        srcType: string;
+        srcProjectId?: string;
+    }) => ContentSourceActions | undefined;
+    /**
+     * Returns the `userContext` of the current user for the content source
+     * specified by `srType`.
+     *
+     * The `userContext` can be used to create, update, delete and publish
+     * documents on behalf of the current user.
+     *
+     * Generally you don't need to pass the `userContext` yourself as it will be
+     * added automatically.
+     *
+     * @param {string} srcType The content source type
+     */
+    getUserContextForContentSourceType: (srcType: string) => User | undefined;
+}
+
+export interface ContentSourceActions {
+    createDocument: (
+        ...args: Parameters<ContentSourceInterface['createDocument']>
+    ) => ReturnType<ContentSourceInterface['createDocument']>;
+    updateDocument: (
+        ...args: Parameters<ContentSourceInterface['updateDocument']>
+    ) => ReturnType<ContentSourceInterface['updateDocument']>;
+    deleteDocument: (
+        ...args: Parameters<ContentSourceInterface['deleteDocument']>
+    ) => ReturnType<ContentSourceInterface['deleteDocument']>;
+    publishDocuments: (
+        ...args: Parameters<ContentSourceInterface['publishDocuments']>
+    ) => ReturnType<ContentSourceInterface['publishDocuments']>;
+}

src/content-source-operation.ts

@@ -1,2 +0,2 @@
-import type { Field, FieldType } from './model-fields';
+import type { Field, FieldListItems, FieldType } from './model-fields';
 
@@ -13,3 +13,3 @@ export type UpdateOperation =
     fieldPath: (string | number)[];
-    modelField: Field;
+    modelField: Field | FieldListItems;
     locale?: string;
@@ -16,0 +16,0 @@ }

src/content-source.ts

@@ -290,3 +290,3 @@ import type { ChildProcessWithoutNullStreams } from 'child_process';
      */
-    hasAccess(options: { userContext?: UserContext }): Promise<{ hasConnection: boolean; hasPermissions: boolean }>;
+    hasAccess(options: { userContext?: User<UserContext> }): Promise<{ hasConnection: boolean; hasPermissions: boolean }>;
 
@@ -316,3 +316,3 @@ /**
         defaultLocaleDocumentId?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<{ documentId: string }>;
@@ -339,3 +339,3 @@
         operations: UpdateOperation[];
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<void>;
@@ -357,3 +357,3 @@
      */
-    deleteDocument(options: { document: Document<DocumentContext>; userContext?: UserContext }): Promise<void>;
+    deleteDocument(options: { document: Document<DocumentContext>; userContext?: User<UserContext> }): Promise<void>;
 
@@ -384,3 +384,3 @@ /**
         locale?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<Asset<AssetContext>>;
@@ -397,3 +397,3 @@
         locale?: string;
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<{ errors: ValidationError[] }>;
@@ -420,3 +420,3 @@
         assets: Asset<AssetContext>[];
-        userContext?: UserContext;
+        userContext?: User<UserContext>;
     }): Promise<void>;
@@ -492,2 +492,7 @@ }
 
+export type User<UserContext = unknown> = {
+    name: string;
+    email: string;
+} & UserContext;
+
 export type UserCommandSpawner = (options: SpawnUserCommandOptions) => ChildProcessWithoutNullStreams;
@@ -494,0 +499,0 @@

No alert changes

Improved metrics

Total package byte prevSize

225140

7.86%

Lines of code

4561

6.42%

No dependency changes