rimecms 0.31.5 → 0.32.0

package/dist/core/pipeline/hooks/validate-fields.server.js

@@ -0,0 +1,170 @@
+import { Hooks } from '../define-hook.js';
+import { PARAMS } from '../../constants.js';
+import { RimeError, RimeFormError } from '../../errors/index.js';
+import { logger } from '../../logger.server.js';
+import { deleteValueAtPath, getValueAtPath, setValueAtPath } from '../../../util/object.js';
+/**
+ * Runs each field's `validate` and its write access check, and throws a `RimeFormError` carrying
+ * every message at once.
+ *
+ * A field the caller may not write is deleted from **both** the data and `context.configMap`.
+ * Leaving its path in the map would make the dropped write look like an explicit "nothing here
+ * any more" and delete the existing rows.
+ *
+ * `?skipValidation=true` skips it, as does the locale-fallback pass, which is re-writing a
+ * document that has already been through this once.
+ */
+export const validateFields = Hooks.beforeUpsert(async function validateFields(args) {
+    const errors = {};
+    const { event, operation } = args;
+    const { rime, user } = event.locals;
+    // Own copy — an access-denied field gets deleted from here too, not just
+    // from `output`. `updateById` turns this map's keys into `incomingPaths`,
+    // which saveRelations/saveBlocks/saveTreeBlocks use to decide which
+    // existing rows are even in scope for this request; leaving a denied
+    // field's path in there made its silently-dropped write look like an
+    // explicit "no relations/blocks here anymore" and delete the existing data.
+    const configMap = { ...args.context.configMap };
+    const locale = args.context.params.locale || args.event.locals.locale;
+    const slug = args.config.slug;
+    const isCollection = rime.config.isCollection(slug);
+    let output = { ...args.data };
+    if (!configMap)
+        throw new RimeError(RimeError.OPERATION_ERROR, 'missing configMap @validateFields');
+    // Get the skip parameter from the url
+    const paramSkip = event.url.searchParams.get(PARAMS.SKIP_VALIDATION) === 'true' || false;
+    // A locale copy writes values validated and hooked once already, where they came from.
+    const copy = !!args.context.isLocaleCopy;
+    const skipUnique = copy || paramSkip;
+    const skipHooks = copy || paramSkip;
+    const skipRequired = copy || paramSkip;
+    const skipAccess = copy || args.context.isSystemOperation;
+    for (const [key, config] of Object.entries(configMap)) {
+        let value = getValueAtPath(key, output);
+        /****************************************************/
+        /* Validation
+        /****************************************************/
+        // Unique
+        /** @TODO better unique check like relations, locale,... */
+        if ('unique' in config.get && config.get.unique && isCollection && !skipUnique) {
+            let query;
+            switch (operation) {
+                case 'create':
+                    query = `where[${key}][equals]=${value}`;
+                    break;
+                case 'update':
+                    if (!args.context.originalDoc)
+                        throw new RimeError(RimeError.OPERATION_ERROR, 'missing originalDoc @validateFields');
+                    query = `where[and][0][${key}][equals]=${value}&where[and][1][id][not_equals]=${args.context.originalDoc.id}&select=id`;
+            }
+            const existing = await rime
+                .collection(slug)
+                .system()
+                .find({ locale, query, select: ['id'] });
+            if (existing.length) {
+                errors[key] = RimeFormError.UNIQUE_FIELD;
+            }
+        }
+        /****************************************************/
+        /* Field hook before validate
+        /****************************************************/
+        if (value !== undefined && value !== null && !skipHooks) {
+            value = await config.use.beforeValidate(value, { config, data: args.data });
+            output = setValueAtPath(key, output, value);
+        }
+        /****************************************************/
+        /* Validate
+        /****************************************************/
+        if (config.get.validate && value !== undefined && value !== null && !skipHooks) {
+            try {
+                const valid = config.use.validate(value, {
+                    data: output,
+                    operation,
+                    id: operation === 'update' ? args.context.originalDoc?.id : undefined,
+                    user: user,
+                    locale,
+                    config: config.get
+                });
+                if (valid !== true) {
+                    errors[key] = valid;
+                }
+            }
+            catch (err) {
+                logger.warn(`Error while validating field ${key}`);
+                console.debug(`[validateFields] field "${key}" threw:`, err);
+                errors[key] = RimeFormError.VALIDATION_ERROR;
+            }
+        }
+        /*
+        /* Field hook before Save
+        */
+        if (value !== undefined && value !== null && !skipHooks) {
+            value = await config.use.beforeSave(value, {
+                config: config.get,
+                event,
+                operation: args.context
+            });
+            output = setValueAtPath(key, output, value);
+        }
+        /****************************************************/
+        /* Access
+        /****************************************************/
+        // Whether this request was denied write access to the field. The field is dropped from
+        // both `output` and `configMap` when so, which also means the caller cannot possibly
+        // satisfy it — see the required check below.
+        let accessDenied = false;
+        if (operation === 'update' && !skipAccess) {
+            const authorizedFieldUpdate = config.use.accessUpdate(user, {
+                id: args.context.originalDoc?.id
+            });
+            if (!authorizedFieldUpdate) {
+                output = deleteValueAtPath(output, key);
+                delete configMap[key];
+                value = undefined;
+                accessDenied = true;
+            }
+        }
+        if (operation === 'create' && !skipAccess) {
+            const authorizedFieldCreate = config.use.accessCreate(user, {
+                id: undefined
+            });
+            if (!authorizedFieldCreate) {
+                output = deleteValueAtPath(output, key);
+                delete configMap[key];
+                value = undefined;
+                accessDenied = true;
+            }
+        }
+        // Required — but never for a field this request may not write. The block above just
+        // emptied `value` itself, so reporting REQUIRED_FIELD here asks the caller for something
+        // it is not allowed to send: an unsatisfiable 400.
+        //
+        // This bit publicly-creatable collections in particular. FormFieldBuilder's default is
+        // `access.create: (user) => !!user`, so on an anonymous POST every field that does not
+        // override it gets stripped, and each `.required()` one then 400s no matter what was
+        // sent. A denied field is not the caller's to provide; it keeps whatever the blank
+        // document or the column default gives it.
+        if (config.get.required && !accessDenied && config.use.isEmpty(value)) {
+            if (skipRequired) {
+                // The field's own type-correct default (falling back to '' only
+                // when none is set) — a hardcoded '' here was wrong for every
+                // non-string required field (number, checkbox, date, ...).
+                output = setValueAtPath(key, output, config.use.defaultValue({ event }) ?? '');
+            }
+            else {
+                errors[key] = RimeFormError.REQUIRED_FIELD;
+            }
+        }
+    }
+    if (Object.keys(errors).length) {
+        throw new RimeFormError(errors);
+    }
+    return {
+        ...args,
+        data: output,
+        context: {
+            ...args.context,
+            configMap
+        }
+    };
+});

package/dist/core/pipeline/persist/blocks/diff.server.d.ts

@@ -0,0 +1,15 @@
+import type { GenericBlock } from '../../../prototype/types.js';
+import type { WithOptional } from '../../../../util/types.js';
+import type { OperationContext } from '../../types.js';
+type BlocksDiff = {
+    toAdd: WithOptional<GenericBlock, 'id'>[];
+    toDelete: GenericBlock[];
+    toUpdate: GenericBlock[];
+};
+type DefineBlocksDiffArgs = {
+    existingBlocks: GenericBlock[];
+    incomingBlocks: WithOptional<GenericBlock, 'id'>[];
+    context: OperationContext;
+};
+export declare function defineBlocksDiff({ existingBlocks, incomingBlocks, context }: DefineBlocksDiffArgs): BlocksDiff;
+export {};

package/dist/core/pipeline/persist/blocks/diff.server.js

@@ -0,0 +1,69 @@
+import { RimeError } from '../../../errors/index.js';
+// Utility to filter out blocks that haven't id
+const blockHasId = (b) => !!b.id;
+export function defineBlocksDiff({ existingBlocks, incomingBlocks, context }) {
+    const configMap = context.configMap;
+    if (!configMap)
+        throw new RimeError(RimeError.OPERATION_ERROR, 'missing configMap @defineBlocksDiff');
+    /////////////////////////////////////////////
+    // Handle add diff
+    //////////////////////////////////////////////
+    // Consider blocks as new if they have temp ID OR no ID at all
+    const toAdd = incomingBlocks.filter((block) => !block.id || block.id.startsWith('temp-'));
+    /////////////////////////////////////////////
+    // Handle delete diff
+    //////////////////////////////////////////////
+    // Consider block to be deleted if its id is not present in incomingBlocks
+    // Note: Existing blocks have been filtered before diff
+    // by removing elements with a path not present in incoming data,
+    // in order to not delete unmodified blocks fields
+    const toDelete = existingBlocks.filter((existing) => {
+        return !incomingBlocks.filter(blockHasId).some((newBlock) => {
+            // Only compare blocks that have real IDs
+            if (newBlock.id.startsWith('temp-'))
+                return false;
+            return newBlock.id === existing.id;
+        });
+    });
+    /////////////////////////////////////////////
+    // Handle update diff
+    //////////////////////////////////////////////
+    // Consider a block that need update :
+    // if its id is present in existing blocks and
+    // if they didn't share same (normalized) props
+    /**
+     * Compare two potential equals block
+     * based on prop normalization and JSON comparaison
+     */
+    function isEqualValues(old, incoming) {
+        // Remove nested blocks to compare block values
+        const normalizeForComparison = (block) => {
+            return Object.entries(block).reduce((acc, [key, value]) => {
+                if (Array.isArray(value) && value[0]?.type) {
+                    return acc;
+                }
+                return { ...acc, [key]: value };
+            }, {});
+        };
+        // Compare
+        const normalizedOld = normalizeForComparison(old);
+        const normalizedNew = normalizeForComparison(incoming);
+        return JSON.stringify(normalizedOld) === JSON.stringify(normalizedNew);
+    }
+    /**
+     * Check wether a block need to be updated
+     */
+    function needUpdate(newBlock) {
+        // Skip blocks with temp IDs
+        if (newBlock.id.startsWith('temp-'))
+            return false;
+        // Check in incomming block if one has the same id than this one
+        const existing = existingBlocks.find((e) => e.id === newBlock.id);
+        if (!existing)
+            return false;
+        // return comparaison
+        return !isEqualValues(existing, newBlock);
+    }
+    const toUpdate = incomingBlocks.filter(blockHasId).filter(needUpdate);
+    return { toAdd, toDelete, toUpdate };
+}

package/dist/core/pipeline/persist/blocks/extract.server.d.ts

@@ -0,0 +1,9 @@
+import type { GenericBlock } from '../../../prototype/types.js';
+import type { Dic } from '../../../../util/types.js';
+import type { ConfigMap } from '../../config-map/types.js';
+type ExtractBlocksArgs = {
+    data: Dic;
+    configMap: ConfigMap;
+};
+export declare function extractBlocks({ data, configMap }: ExtractBlocksArgs): GenericBlock[];
+export {};

package/dist/core/pipeline/persist/blocks/extract.server.js

@@ -0,0 +1,33 @@
+import { normalizeFieldPath } from '../../../../util/path.js';
+import { getValueAtPath } from '../../../../util/object.js';
+export function extractBlocks({ data, configMap }) {
+    const blocks = [];
+    Object.entries(configMap).forEach(([path, config]) => {
+        if (config.type === 'blocks') {
+            const value = getValueAtPath(path, data);
+            const isEmptyValue = config.use.isEmpty(value);
+            if (value && !isEmptyValue) {
+                value.forEach((block, index) => {
+                    if (block.type) {
+                        const cleanBlock = {
+                            ...block,
+                            path: normalizeFieldPath(block.path || path),
+                            position: block.position ?? index
+                        };
+                        // Remove children blocks
+                        const finalBlock = Object.entries(cleanBlock).reduce((acc, [key, value]) => {
+                            const nestedPath = `${path}.${index}.${key}`;
+                            if (configMap[nestedPath]?.type === 'blocks') {
+                                return acc;
+                            }
+                            // @TODO should maybe remove tree also
+                            return { ...acc, [key]: value };
+                        }, {});
+                        blocks.push(finalBlock);
+                    }
+                });
+            }
+        }
+    });
+    return blocks;
+}

package/dist/core/pipeline/persist/blocks/index.server.d.ts

@@ -0,0 +1,27 @@
+import type { Adapter } from '../../../adapter.js';
+import type { GenericBlock, PrototypeSlug } from '../../../prototype/types.js';
+import type { Dic } from '../../../../util/types.js';
+import type { OperationContext } from '../../types.js';
+/**
+ * Saves blocks to the database by comparing incoming blocks with existing ones
+ * and performing create, update, and delete operations as needed.
+ *
+ * This function handles the complete lifecycle of block persistence:
+ * 1. Extract blocks from form data
+ * 2. Compare with existing blocks to determine changes
+ * 3. Execute database operations (create/update/delete)
+ */
+export declare const saveBlocks: (args: {
+    context: OperationContext;
+    ownerId: string;
+    data: Dic;
+    incomingPaths: string[];
+    adapter: Adapter;
+    /** Whose children these are — the versions's slug when the prototype has one. Resolved by
+     *  `persistRelational` from what the prototype was registered with. */
+    ownerSlug: PrototypeSlug;
+}) => Promise<{
+    toAdd: import("../../../../util/types.js").WithOptional<GenericBlock, "id">[];
+    toDelete: GenericBlock[];
+    toUpdate: GenericBlock[];
+}>;

package/dist/core/pipeline/persist/blocks/index.server.js

@@ -0,0 +1,68 @@
+import { RimeError } from '../../../errors/index.js';
+import { defineBlocksDiff } from './diff.server.js';
+import { extractBlocks } from './extract.server.js';
+/**
+ * Saves blocks to the database by comparing incoming blocks with existing ones
+ * and performing create, update, and delete operations as needed.
+ *
+ * This function handles the complete lifecycle of block persistence:
+ * 1. Extract blocks from form data
+ * 2. Compare with existing blocks to determine changes
+ * 3. Execute database operations (create/update/delete)
+ */
+export const saveBlocks = async (args) => {
+    //
+    const { context, ownerId, data, incomingPaths, adapter, ownerSlug } = args;
+    const { locale } = context.params;
+    const { originalDoc: original, configMap, originalConfigMap } = context;
+    if (!configMap || !ownerId)
+        throw new RimeError(RimeError.OPERATION_ERROR, '@saveBlocks');
+    // Extract all blocks from the incoming form data using the current config
+    const incomingBlocks = extractBlocks({
+        data,
+        configMap
+    });
+    let existingBlocks = [];
+    // If we have an original document (i.e., this is an update operation)
+    if (original) {
+        if (!originalConfigMap)
+            throw new RimeError(RimeError.OPERATION_ERROR, 'missing original');
+        // Extract blocks from the original document using its config
+        const blocks = extractBlocks({
+            data: original,
+            configMap: originalConfigMap
+        });
+        // Only consider existing blocks that are in paths being updated
+        // This optimization prevents deletion of blocks in unmodified form sections
+        // For example, if only "content.hero" was modified, we don't want to
+        // accidentally delete blocks in "content.footer"
+        existingBlocks = blocks.filter((block) => {
+            return incomingPaths.some((path) => block.path?.startsWith(path));
+        });
+    }
+    // Calculate what blocks need to be added, updated, or deleted
+    // This handles localization logic and compares block properties
+    const blocksDiff = defineBlocksDiff({
+        existingBlocks,
+        incomingBlocks,
+        context
+    });
+    // Execute delete operations first to avoid potential conflicts
+    if (blocksDiff.toDelete.length) {
+        await Promise.all(blocksDiff.toDelete.map((block) => adapter.blocks.delete({ parentSlug: ownerSlug, block })));
+    }
+    // Create new blocks (blocks without IDs or with temporary IDs)
+    if (blocksDiff.toAdd.length) {
+        await Promise.all(blocksDiff.toAdd.map((block) => adapter.blocks.create({
+            parentSlug: ownerSlug,
+            ownerId,
+            block,
+            locale
+        })));
+    }
+    // Update existing blocks that have changed properties
+    if (blocksDiff.toUpdate.length) {
+        await Promise.all(blocksDiff.toUpdate.map((block) => adapter.blocks.update({ parentSlug: ownerSlug, block, locale: locale })));
+    }
+    return blocksDiff;
+};

package/dist/core/pipeline/persist/relations/diff.server.d.ts

@@ -0,0 +1,14 @@
+import type { BeforeOperationRelation } from '../../../../fields/relation/index.js';
+import type { Relation } from '../../../../fields/relation/index.js';
+export type RelationDiff = {
+    toAdd: BeforeOperationRelation[];
+    toDelete: Relation[];
+    toUpdate: Relation[];
+};
+type Args = {
+    existingRelations: Relation[];
+    incomingRelations: BeforeOperationRelation[];
+    locale?: string;
+};
+export declare const defineRelationsDiff: ({ existingRelations, incomingRelations, locale }: Args) => RelationDiff;
+export {};

package/dist/core/pipeline/persist/relations/diff.server.js

@@ -0,0 +1,47 @@
+import { pathToRegex } from '../../../fields/util.js';
+const needUpdate = (existing, incoming) => !(existing.position === incoming.position &&
+    existing[`${incoming.relationTo}Id`] === incoming.documentId &&
+    existing.path === incoming.path &&
+    (incoming.locale ? existing.locale === incoming.locale : existing.locale === null));
+export const defineRelationsDiff = ({ existingRelations, incomingRelations, locale }) => {
+    const toAdd = [];
+    const toDelete = [];
+    const toUpdate = [];
+    const processedIds = new Set(); // Keep track of processed IDs
+    // Process incoming relations
+    for (const incoming of incomingRelations) {
+        const existingMatch = existingRelations.find((existing) => (incoming.id && existing.id === incoming.id) ||
+            (!incoming.id &&
+                existing[`${incoming.relationTo}Id`] === incoming.documentId &&
+                existing.path === incoming.path &&
+                (incoming.locale ? existing.locale === incoming.locale : existing.locale === null)));
+        if (existingMatch) {
+            // Only add to toUpdate if we haven't processed this ID yet and if not all props are the same
+            if (!processedIds.has(existingMatch.id) && needUpdate(existingMatch, incoming)) {
+                toUpdate.push({
+                    ...existingMatch,
+                    path: incoming.path,
+                    position: incoming.position
+                });
+                processedIds.add(existingMatch.id);
+            }
+        }
+        else {
+            toAdd.push(incoming);
+        }
+    }
+    // Find relations to delete
+    toDelete.push(...existingRelations.filter((existing) => {
+        // Keep relations from other locales
+        if (existing.locale && existing.locale !== locale) {
+            return false;
+        }
+        // Delete if not found in incoming relations
+        return !incomingRelations.some((incoming) => (incoming.id && existing.id === incoming.id) ||
+            (!incoming.id &&
+                existing[`${incoming.relationTo}Id`] === incoming.documentId &&
+                pathToRegex(existing.path).test(incoming.path) &&
+                (incoming.locale ? existing.locale === incoming.locale : existing.locale === null)));
+    }));
+    return { toAdd, toDelete, toUpdate };
+};

package/dist/core/pipeline/persist/relations/extract.server.d.ts

@@ -0,0 +1,11 @@
+import type { BeforeOperationRelation } from '../../../../fields/relation/index.js';
+import type { Dic } from '../../../../util/types.js';
+import type { ConfigMap } from '../../config-map/types.js';
+type Args = {
+    ownerId?: string;
+    data: Dic;
+    configMap: ConfigMap;
+    locale: string | undefined;
+};
+export declare const extractRelations: ({ ownerId, data, configMap, locale }: Args) => BeforeOperationRelation[];
+export {};

package/dist/core/pipeline/persist/relations/extract.server.js

@@ -0,0 +1,59 @@
+import { RelationFieldBuilder } from '../../../../fields/relation/index.js';
+import { getValueAtPath } from '../../../../util/object.js';
+export const extractRelations = ({ ownerId, data, configMap, locale }) => {
+    const relations = [];
+    for (const [path, config] of Object.entries(configMap)) {
+        if (config instanceof RelationFieldBuilder) {
+            const value = getValueAtPath(path, data);
+            const localized = config.get.localized;
+            const relationRawValue = value;
+            let output = [];
+            const relationFromString = ({ value, position = 0 }) => {
+                const result = {
+                    position,
+                    relationTo: config.get.relationTo,
+                    documentId: value,
+                    ownerId,
+                    path
+                };
+                if (localized) {
+                    result.locale = locale;
+                }
+                return result;
+            };
+            const completeRelation = ({ value, position = 0 }) => {
+                const result = {
+                    id: value.id || undefined,
+                    position,
+                    relationTo: config.get.relationTo,
+                    documentId: value.documentId,
+                    ownerId,
+                    path
+                };
+                if (localized) {
+                    result.locale = locale;
+                }
+                return result;
+            };
+            // If value is array
+            if (Array.isArray(relationRawValue)) {
+                output = relationRawValue.map((value, n) => {
+                    // Array of string build the relation value
+                    if (typeof value === 'string') {
+                        return relationFromString({ value, position: n });
+                    }
+                    else {
+                        // Complete possible missing props
+                        return completeRelation({ value, position: n });
+                    }
+                });
+                // Check if it's a string
+            }
+            else if (typeof relationRawValue === 'string') {
+                output = [relationFromString({ value: relationRawValue, position: 0 })];
+            }
+            relations.push(...output);
+        }
+    }
+    return relations;
+};

package/dist/core/pipeline/persist/relations/index.server.d.ts

@@ -0,0 +1,26 @@
+import type { Adapter } from '../../../adapter.js';
+import type { GenericBlock, PrototypeSlug } from '../../../prototype/types.js';
+import type { Dic } from '../../../../util/types.js';
+import type { ConfigMap } from '../../config-map/types.js';
+import type { TreeBlocksDiff } from '../tree/diff.server.js';
+type Diff<T> = {
+    toAdd: (Omit<T, 'id'> & {
+        id?: string;
+    })[];
+    toDelete: T[];
+    toUpdate: T[];
+};
+export declare const saveRelations: (args: {
+    data: Dic;
+    configMap: ConfigMap;
+    incomingPaths: string[];
+    blocksDiff: Diff<GenericBlock>;
+    treeDiff: TreeBlocksDiff;
+    adapter: Adapter;
+    locale?: string;
+    /** Whose children these are — the versions's slug when the prototype has one. Resolved by
+     *  `persistRelational` from what the prototype was registered with. */
+    ownerSlug: PrototypeSlug;
+    ownerId: string;
+}) => Promise<import("./diff.server.js").RelationDiff>;
+export {};

package/dist/core/pipeline/persist/relations/index.server.js

@@ -0,0 +1,66 @@
+import { defineRelationsDiff } from './diff.server.js';
+import { extractRelations } from './extract.server.js';
+export const saveRelations = async (args) => {
+    const { configMap, incomingPaths, blocksDiff, treeDiff, adapter, locale, ownerSlug, ownerId, data } = args;
+    /** Delete relations from deletedBlocks */
+    await adapter.relations.deleteFromPaths({
+        parentSlug: ownerSlug,
+        ownerId,
+        paths: blocksDiff.toDelete.map((block) => `${block.path}.${block.position}`),
+        locale
+    });
+    /** Delete relations from deletedTreeItems */
+    await adapter.relations.deleteFromPaths({
+        parentSlug: ownerSlug,
+        ownerId,
+        paths: treeDiff.toDelete.map((block) => `${block.path}.${block.position}`),
+        locale
+    });
+    /** Get relations in data */
+    const incomingRelations = extractRelations({
+        ownerId,
+        data,
+        configMap,
+        locale
+    });
+    // get existing relations filtered by path
+    // if not present in incoming paths don't keep it.
+    const existingRelations = await adapter.relations
+        .getAll({
+        parentSlug: ownerSlug,
+        ownerId,
+        locale: locale
+    })
+        .then((relations) => {
+        // Filter existing relations
+        return relations.filter((relation) => {
+            return incomingPaths.some((path) => relation.path?.startsWith(path));
+        });
+    });
+    /** get difference between them */
+    const relationsDiff = defineRelationsDiff({
+        existingRelations,
+        incomingRelations,
+        locale: locale
+    });
+    if (relationsDiff.toDelete.length) {
+        await adapter.relations.delete({
+            parentSlug: ownerSlug,
+            relations: relationsDiff.toDelete
+        });
+    }
+    if (relationsDiff.toUpdate.length) {
+        await adapter.relations.update({
+            parentSlug: ownerSlug,
+            relations: relationsDiff.toUpdate
+        });
+    }
+    if (relationsDiff.toAdd.length) {
+        await adapter.relations.create({
+            parentSlug: ownerSlug,
+            ownerId,
+            relations: relationsDiff.toAdd
+        });
+    }
+    return relationsDiff;
+};

package/dist/core/pipeline/persist/tree/diff.server.d.ts

@@ -0,0 +1,20 @@
+import type { TreeBlock } from '../../../prototype/types.js';
+import type { WithRequired } from '../../../../util/types.js';
+import type { OperationContext } from '../../types.js';
+type TreeBlockWithPath = WithRequired<TreeBlock, 'path'>;
+type TreeBlockForUpdate = Omit<TreeBlock, 'id' | 'path'> & {
+    id?: string;
+    path: string;
+};
+export type TreeBlocksDiff = {
+    toAdd: TreeBlockWithPath[];
+    toDelete: TreeBlockWithPath[];
+    toUpdate: TreeBlockForUpdate[];
+};
+type DefineTreeBlocksDiffArgs = {
+    existingBlocks: TreeBlockWithPath[];
+    incomingBlocks: TreeBlockForUpdate[];
+    context: OperationContext;
+};
+export declare function defineTreeBlocksDiff({ existingBlocks, incomingBlocks, context }: DefineTreeBlocksDiffArgs): TreeBlocksDiff;
+export {};