studiocms/dist/virtuals/sdk/modules/diffTracking.d.ts

Astro Native CMS for AstroDB. Built from the ground up by the Astro community.

import { type Diff2HtmlConfig } from 'diff2html';
import { Effect } from '../../../effect.js';
import { AstroDB, SDKCore_Parsers } from '../effect/index.js';
import { SDKCoreError } from '../errors.js';
import type { tsPageDataSelect } from '../types/index.js';
declare const SDKCore_DiffTracking_base: Effect.Service.Class<SDKCore_DiffTracking, "studiocms/sdk/SDKCore/modules/diffTracking", {
    readonly dependencies: readonly [import("effect/Layer").Layer<AstroDB, never, never>, import("effect/Layer").Layer<SDKCore_Parsers, never, never>];
    readonly effect: Effect.Effect<{
        /**
         * Inserts a new diff entry for a page.
         * @param userId - The ID of the user who made the changes.
         * @param pageId - The ID of the page being modified.
         * @param data - The content and metadata before and after the change.
         * @param diffLength - The maximum number of diffs to keep for the page.
         * @returns An Effect that resolves to the fixed diff entry.
         * @throws {SDKCoreError} If an error occurs during the database operations.
         * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
         */
        insert: (userId: string, pageId: string, data: {
            content: {
                start: string;
                end: string;
            };
            metaData: {
                start: Partial<tsPageDataSelect>;
                end: Partial<tsPageDataSelect>;
            };
        }, diffLength: number) => Effect.Effect<import("../types/index.js").diffReturn, SDKCoreError, never>;
        /**
         * Clears all diffs for a page.
         * @param pageId - The ID of the page to clear diffs for.
         * @returns An Effect that resolves to void.
         * @throws {SDKCoreError} If an error occurs during the database operations.
         * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
         */
        clear: (pageId: string) => Effect.Effect<import("@libsql/client").ResultSet, SDKCoreError, never>;
        get: {
            byPageId: {
                /**
                 * Retrieves all diffs for a page.
                 * @param pageId - The ID of the page to retrieve diffs for.
                 * @returns An Effect that resolves to the fixed diff entries.
                 * @throws {SDKCoreError} If an error occurs during the database operations.
                 * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
                 */
                all: (pageId: string) => Effect.Effect<import("../types/index.js").diffReturn[], SDKCoreError, never>;
                /**
                 * Retrieves the latest N diffs for a page.
                 * @param pageId - The ID of the page to retrieve diffs for.
                 * @param count - The number of latest diffs to retrieve.
                 * @returns An Effect that resolves to the fixed diff entries.
                 * @throws {SDKCoreError} If an error occurs during the database operations.
                 * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
                 */
                latest: (pageId: string, count: number) => Effect.Effect<import("../types/index.js").diffReturn[], SDKCoreError, never>;
            };
            byUserId: {
                /**
                 * Retrieves all diffs created by a user.
                 * @param userId - The ID of the user whose diffs to retrieve.
                 * @returns An Effect that resolves to the fixed diff entries.
                 * @throws {SDKCoreError} If an error occurs during the database operations.
                 * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
                 */
                all: (userId: string) => Effect.Effect<import("../types/index.js").diffReturn[], SDKCoreError, never>;
                /**
                 * Retrieves the latest N diffs created by a user.
                 * @param userId - The ID of the user whose diffs to retrieve.
                 * @param count - The number of latest diffs to retrieve.
                 * @returns An Effect that resolves to the fixed diff entries.
                 * @throws {SDKCoreError} If an error occurs during the database operations.
                 * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
                 */
                latest: (userId: string, count: number) => Effect.Effect<import("../types/index.js").diffReturn[], SDKCoreError, never>;
            };
            /**
             * Retrieves a single diff entry by its ID.
             * @param id - The ID of the diff entry to retrieve.
             * @returns An Effect that resolves to the fixed diff entry.
             * @throws {SDKCoreError} If the diff entry is not found.
             * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
             */
            single: (id: string) => Effect.Effect<import("../types/index.js").diffReturn | undefined, SDKCoreError, never>;
        };
        /**
         * Reverts page content and/or metadata to a specific diff and purges newer diffs.
         * @param id - The ID of the diff to revert to.
         * @param type - The type of data to revert: 'content', 'data', or 'both'.
         * @returns An Effect that resolves to the fixed diff entry after the revert.
         * @throws {SDKCoreError} If the diff entry is not found or if the JSON in `pageMetaData` is invalid.
         * @throws {LibSQLDatabaseError} If an error occurs during the database operations.
         */
        revertToDiff: (id: string, type: "content" | "data" | "both") => Effect.Effect<import("../types/index.js").diffReturn, SDKCoreError, never>;
        utils: {
            /**
             * Compares two metadata objects and returns their differences.
             * @param obj1 - The first metadata object to compare.
             * @param obj2 - The second metadata object to compare.
             * @returns An Effect that resolves to an array of differences.
             * @throws {UnknownException} If an error occurs during the comparison process.
             */
            getMetaDataDifferences: <T extends Record<string, unknown>>(obj1: T, obj2: T) => Effect.Effect<{
                label: string;
                previous: unknown;
                current: unknown;
            }[], SDKCoreError, never>;
            /**
             * Converts a diff string into HTML format.
             * @param diff - The diff string to convert.
             * @param options - Optional configuration for the HTML output.
             * @returns An Effect that resolves to the HTML representation of the diff.
             * @throws {UnknownException} If an error occurs during the conversion process.
             */
            getDiffHTML: (diff: string | null, options?: Diff2HtmlConfig) => Effect.Effect<string, SDKCoreError, never>;
        };
    }, never, AstroDB | SDKCore_Parsers>;
}>;
/**
 * Provides diff tracking functionality for StudioCMS SDKCore.
 *
 * This service enables tracking, storing, retrieving, and reverting changes (diffs) made to page content and metadata.
 * It integrates with AstroDB and SDKCore_Parsers, and handles database operations with error management.
 *
 * ## Features
 * - Insert new diffs for page content and metadata.
 * - Limit the number of stored diffs per page, removing the oldest when exceeding the limit.
 * - Clear all diffs for a given page.
 * - Retrieve all or latest diffs by page ID or user ID.
 * - Retrieve a single diff by its ID.
 * - Revert page content and/or metadata to a specific diff, purging newer diffs.
 * - Utility methods for comparing metadata and rendering diffs as HTML.
 *
 * ## Error Handling
 * All database operations are wrapped with error handling, returning `SDKCoreError` on failure.
 *
 * ## Dependencies
 * - AstroDB.Default
 * - SDKCore_Parsers.Default
 *
 * ## Methods
 * - `insert(userId, pageId, data, diffLength)`: Inserts a new diff entry.
 * - `clear(pageId)`: Removes all diffs for a page.
 * - `get.byPageId.all(pageId)`: Gets all diffs for a page.
 * - `get.byPageId.latest(pageId, count)`: Gets the latest N diffs for a page.
 * - `get.byUserId.all(userId)`: Gets all diffs created by a user.
 * - `get.byUserId.latest(userId, count)`: Gets the latest N diffs by a user.
 * - `get.single(id)`: Gets a single diff by ID.
 * - `revertToDiff(id, type)`: Reverts page content and/or metadata to a specific diff and purges newer diffs.
 * - `utils.getMetaDataDifferences(obj1, obj2)`: Compares two metadata objects and returns their differences.
 * - `utils.getDiffHTML(diff, options)`: Renders a diff string as HTML.
 *
 * @remarks
 * This service is intended for internal use within the StudioCMS SDKCore and relies on Drizzle ORM for database operations.
 */
export declare class SDKCore_DiffTracking extends SDKCore_DiffTracking_base {
}
export {};