snapshot of https://github.com/toeverything/AFFiNE.git (canary, 2026-09-16; blobs > 131072B omitted)

blocksuite/framework/store/src/schema/schema.ts

@@ -0,0 +1,325 @@
+import { minimatch } from 'minimatch';
+
+import { SCHEMA_NOT_FOUND_MESSAGE } from '../consts.js';
+import { BlockSchema, type BlockSchemaType } from '../model/block/zod.js';
+import { SchemaValidateError } from './error.js';
+
+/**
+ * Represents a schema manager for block flavours and their relationships.
+ * Provides methods to register, validate, and query block schemas.
+ */
+export class Schema {
+  /**
+   * A map storing block flavour names to their corresponding schema definitions.
+   */
+  readonly flavourSchemaMap = new Map<string, BlockSchemaType>();
+
+  /**
+   * Safely validates the schema relationship for a given flavour, parent, and children.
+   * Returns true if valid, false otherwise (does not throw).
+   *
+   * @param flavour - The block flavour to validate.
+   * @param parentFlavour - The parent block flavour (optional).
+   * @param childFlavours - The child block flavours (optional).
+   * @returns True if the schema relationship is valid, false otherwise.
+   */
+  safeValidate = (
+    flavour: string,
+    parentFlavour?: string,
+    childFlavours?: string[]
+  ): boolean => {
+    try {
+      this.validate(flavour, parentFlavour, childFlavours);
+      return true;
+    } catch {
+      return false;
+    }
+  };
+
+  /**
+   * Retrieves the schema for a given block flavour.
+   *
+   * @param flavour - The block flavour name.
+   * @returns The corresponding BlockSchemaType or undefined if not found.
+   */
+  get(flavour: string) {
+    return this.flavourSchemaMap.get(flavour);
+  }
+
+  /**
+   * Validates the schema relationship for a given flavour, parent, and children.
+   * Throws SchemaValidateError if invalid.
+   *
+   * @param flavour - The block flavour to validate.
+   * @param parentFlavour - The parent block flavour (optional).
+   * @param childFlavours - The child block flavours (optional).
+   * @throws {SchemaValidateError} If the schema relationship is invalid.
+   */
+  validate = (
+    flavour: string,
+    parentFlavour?: string,
+    childFlavours?: string[]
+  ): void => {
+    const schema = this.flavourSchemaMap.get(flavour);
+    if (!schema) {
+      throw new SchemaValidateError(flavour, SCHEMA_NOT_FOUND_MESSAGE);
+    }
+
+    const validateChildren = () => {
+      childFlavours?.forEach(childFlavour => {
+        const childSchema = this.flavourSchemaMap.get(childFlavour);
+        if (!childSchema) {
+          throw new SchemaValidateError(childFlavour, SCHEMA_NOT_FOUND_MESSAGE);
+        }
+        this.validateSchema(childSchema, schema);
+      });
+    };
+
+    if (schema.model.role === 'root') {
+      if (parentFlavour) {
+        throw new SchemaValidateError(
+          schema.model.flavour,
+          'Root block cannot have parent.'
+        );
+      }
+
+      validateChildren();
+      return;
+    }
+
+    if (!parentFlavour) {
+      throw new SchemaValidateError(
+        schema.model.flavour,
+        'None root block must have parent.'
+      );
+    }
+
+    const parentSchema = this.flavourSchemaMap.get(parentFlavour);
+    if (!parentSchema) {
+      throw new SchemaValidateError(parentFlavour, SCHEMA_NOT_FOUND_MESSAGE);
+    }
+    this.validateSchema(schema, parentSchema);
+    validateChildren();
+  };
+
+  /**
+   * Returns an object mapping each registered flavour to its version number.
+   */
+  get versions() {
+    return Object.fromEntries(
+      Array.from(this.flavourSchemaMap.values()).map(
+        (schema): [string, number] => [schema.model.flavour, schema.version]
+      )
+    );
+  }
+
+  /**
+   * Checks if two flavours match, using minimatch for wildcard support.
+   *
+   * @param childFlavour - The child block flavour.
+   * @param parentFlavour - The parent block flavour.
+   * @returns True if the flavours match, false otherwise.
+   */
+  private _matchFlavour(childFlavour: string, parentFlavour: string) {
+    return (
+      minimatch(childFlavour, parentFlavour) ||
+      minimatch(parentFlavour, childFlavour)
+    );
+  }
+
+  /**
+   * Checks if two values match as either flavours or roles, supporting role syntax (e.g., '@role').
+   *
+   * @param childValue - The child value (flavour or role).
+   * @param parentValue - The parent value (flavour or role).
+   * @param childRole - The actual role of the child.
+   * @param parentRole - The actual role of the parent.
+   * @returns True if the values match as flavours or roles, false otherwise.
+   */
+  private _matchFlavourOrRole(
+    childValue: string,
+    parentValue: string,
+    childRole: string,
+    parentRole: string
+  ): boolean {
+    // Check if either value starts with '@' indicating it's a role
+    const isChildRole = childValue.startsWith('@');
+    const isParentRole = parentValue.startsWith('@');
+
+    // If both are roles, do exact match
+    if (isChildRole && isParentRole) {
+      return childValue === parentValue;
+    }
+    // If child is role, compare with parent's actual role
+    if (isChildRole) {
+      return childValue === `@${parentRole}`;
+    }
+    // If parent is role, compare with child's actual role
+    if (isParentRole) {
+      return parentValue === `@${childRole}`;
+    }
+    // If neither is role, use flavour matching
+    return this._matchFlavour(childValue, parentValue);
+  }
+
+  /**
+   * Validates if the parent schema is a valid parent for the child schema.
+   *
+   * @param child - The child block schema.
+   * @param parent - The parent block schema.
+   * @returns True if the parent is valid for the child, false otherwise.
+   */
+  private _validateParent(
+    child: BlockSchemaType,
+    parent: BlockSchemaType
+  ): boolean {
+    const _childFlavour = child.model.flavour;
+    const _parentFlavour = parent.model.flavour;
+    const _childRole = child.model.role;
+    const _parentRole = parent.model.role;
+
+    const childValidFlavourOrRole = child.model.parent || ['*'];
+    const parentValidFlavourOrRole = parent.model.children || ['*'];
+
+    return parentValidFlavourOrRole.some(parentValidFlavourOrRole => {
+      return childValidFlavourOrRole.some(childValidFlavourOrRole => {
+        if (
+          parentValidFlavourOrRole === '*' &&
+          childValidFlavourOrRole === '*'
+        ) {
+          return true;
+        }
+
+        if (parentValidFlavourOrRole === '*') {
+          return this._matchFlavourOrRole(
+            childValidFlavourOrRole,
+            _parentFlavour,
+            _childRole,
+            _parentRole
+          );
+        }
+
+        if (childValidFlavourOrRole === '*') {
+          return this._matchFlavourOrRole(
+            _childFlavour,
+            parentValidFlavourOrRole,
+            _childRole,
+            _parentRole
+          );
+        }
+
+        return (
+          this._matchFlavourOrRole(
+            _childFlavour,
+            parentValidFlavourOrRole,
+            _childRole,
+            _parentRole
+          ) &&
+          this._matchFlavourOrRole(
+            childValidFlavourOrRole,
+            _parentFlavour,
+            _childRole,
+            _parentRole
+          )
+        );
+      });
+    });
+  }
+
+  /**
+   * Validates the role relationship between child and parent schemas.
+   * Throws if the child is a root block but has a parent.
+   *
+   * @param child - The child block schema.
+   * @param parent - The parent block schema.
+   * @throws {SchemaValidateError} If the child is a root block with a parent.
+   */
+  private _validateRole(child: BlockSchemaType, parent: BlockSchemaType) {
+    const childRole = child.model.role;
+    const childFlavour = child.model.flavour;
+    const parentFlavour = parent.model.flavour;
+
+    if (childRole === 'root') {
+      throw new SchemaValidateError(
+        childFlavour,
+        `Root block cannot have parent: ${parentFlavour}.`
+      );
+    }
+  }
+
+  /**
+   * Checks if the child flavour is valid under the parent flavour.
+   *
+   * @param child - The child block flavour name.
+   * @param parent - The parent block flavour name.
+   * @returns True if the relationship is valid, false otherwise.
+   */
+  isValid(child: string, parent: string) {
+    const childSchema = this.flavourSchemaMap.get(child);
+    const parentSchema = this.flavourSchemaMap.get(parent);
+    if (!childSchema || !parentSchema) {
+      return false;
+    }
+    try {
+      this.validateSchema(childSchema, parentSchema);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Registers an array of block schemas into the schema manager.
+   *
+   * @param blockSchema - An array of block schema definitions to register.
+   * @returns The Schema instance (for chaining).
+   */
+  register(blockSchema: BlockSchemaType[]) {
+    blockSchema.forEach(schema => {
+      BlockSchema.parse(schema);
+      this.flavourSchemaMap.set(schema.model.flavour, schema);
+    });
+    return this;
+  }
+
+  /**
+   * Serializes the schema map to a plain object for JSON output.
+   *
+   * @returns An object mapping each flavour to its role, parent, and children.
+   */
+  toJSON() {
+    return Object.fromEntries(
+      Array.from(this.flavourSchemaMap.values()).map(
+        (schema): [string, Record<string, unknown>] => [
+          schema.model.flavour,
+          {
+            role: schema.model.role,
+            parent: schema.model.parent,
+            children: schema.model.children,
+          },
+        ]
+      )
+    );
+  }
+
+  /**
+   * Validates the relationship between a child and parent schema.
+   * Throws if the relationship is invalid.
+   *
+   * @param child - The child block schema.
+   * @param parent - The parent block schema.
+   * @throws {SchemaValidateError} If the relationship is invalid.
+   */
+  validateSchema(child: BlockSchemaType, parent: BlockSchemaType) {
+    this._validateRole(child, parent);
+
+    const relationCheckSuccess = this._validateParent(child, parent);
+
+    if (!relationCheckSuccess) {
+      throw new SchemaValidateError(
+        child.model.flavour,
+        `Block cannot have parent: ${parent.model.flavour}.`
+      );
+    }
+  }
+}