@milaboratories/pl-model-common 1.15.8 → 1.16.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milaboratories/pl-model-common",
-  "version": "1.15.8",
+  "version": "1.16.0",
   "description": "Platforma SDK Model",
   "types": "./dist/index.d.ts",
   "main": "./dist/index.js",
@@ -23,7 +23,7 @@
   },
   "devDependencies": {
     "eslint": "^9.25.1",
-    "typescript": "~5.5.4",
+    "typescript": "~5.6.3",
     "vite": "^6.3.5",
     "vitest": "^2.1.9",
     "@milaboratories/build-configs": "1.0.4",

package/src/bmodel/block_config.ts

@@ -0,0 +1,69 @@
+// TODO BroadActiveHandleDescriptor must be removed
+
+import type { BlockCodeFeatureFlags } from '../flags';
+import type { BlockCodeWithInfo, Code } from './code';
+import type { BlockRenderingMode } from './types';
+
+/**
+ * BroadActiveHandleDescriptor = TypedConfigOrConfigLambda,
+ * NarrowActiveHandleDescriptor = ConfigRenderLambda
+ */
+export type BlockConfigV3Generic<
+  Args = unknown,
+  UiState = unknown,
+  BroadActiveHandleDescriptor = unknown,
+  NarrowActiveHandleDescriptor extends BroadActiveHandleDescriptor = BroadActiveHandleDescriptor,
+  Outputs extends Record<string, BroadActiveHandleDescriptor> = Record<string, BroadActiveHandleDescriptor>,
+> = {
+  /** SDK version used by the block */
+  readonly sdkVersion: string;
+
+  /** Main rendering mode for the block */
+  readonly renderingMode: BlockRenderingMode;
+
+  /** Initial value for the args when block is added to the project */
+  readonly initialArgs: Args;
+
+  /** Initial value for the args when block is added to the project */
+  readonly initialUiState: UiState;
+
+  /**
+   * Config to determine whether the block can be executed with current
+   * arguments.
+   *
+   * Optional to support earlier SDK version configs.
+   * */
+  readonly inputsValid: BroadActiveHandleDescriptor;
+
+  /** Configuration to derive list of section for the left overview panel */
+  readonly sections: BroadActiveHandleDescriptor;
+
+  /** Lambda to derive block title */
+  readonly title?: NarrowActiveHandleDescriptor;
+
+  /**
+   * Lambda returning list of upstream blocks this block enriches with its exports,
+   * influences dependency graph construction
+   * */
+  readonly enrichmentTargets?: NarrowActiveHandleDescriptor;
+
+  /** Configuration for the output cells */
+  readonly outputs: Outputs;
+
+  /** Config code bundle */
+  readonly code?: Code;
+
+  /** Feature flags for the block Model and UI code. */
+  readonly featureFlags?: BlockCodeFeatureFlags;
+};
+
+export type BlockConfigGeneric = BlockConfigV3Generic;
+
+export function extractCodeWithInfo(cfg: BlockConfigV3Generic): BlockCodeWithInfo | undefined {
+  if (cfg.code === undefined) return undefined;
+  return {
+    code: cfg.code,
+    sdkVersion: cfg.sdkVersion,
+    featureFlags: cfg.featureFlags,
+  };
+}

package/src/bmodel/code.ts

@@ -0,0 +1,12 @@
+import type { BlockCodeFeatureFlags } from '../flags';
+
+export type Code = {
+  type: 'plain';
+  content: string;
+};
+
+export type BlockCodeWithInfo = {
+  readonly code: Code;
+  readonly sdkVersion: string;
+  readonly featureFlags: BlockCodeFeatureFlags | undefined;
+};

package/src/bmodel/container.ts

@@ -0,0 +1,58 @@
+import type { BlockConfigV3Generic } from './block_config';
+import type { Code } from './code';
+import type { BlockRenderingMode } from './types';
+
+/** Container simplifying maintenance of forward and backward compatibility */
+export type BlockConfigContainer = {
+  /** Actual config */
+  readonly v3: Omit<BlockConfigV3Generic, 'code'>;
+
+  /** Config code bundle */
+  readonly code?: Code;
+
+  //
+  // Fields below are used to read previous config versions
+  //
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly sdkVersion?: string;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly renderingMode?: BlockRenderingMode;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly initialArgs?: unknown;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly canRun?: unknown;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly inputsValid?: unknown;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly sections?: unknown;
+
+  /**
+   * For backward compatibility
+   * @deprecated
+   */
+  readonly outputs?: Record<string, unknown>;
+};

package/src/bmodel/index.ts

@@ -0,0 +1,5 @@
+export * from './block_config';
+export * from './code';
+export * from './types';
+export * from './container';
+export * from './normalization';

package/src/bmodel/normalization.ts

@@ -0,0 +1,111 @@
+import type { BlockConfigGeneric } from './block_config';
+import type { BlockConfigContainer } from './container';
+
+function upgradeCfgOrLambda(data: any): any;
+function upgradeCfgOrLambda(
+  data: any | undefined
+): any | undefined;
+function upgradeCfgOrLambda(
+  data: any | undefined,
+): any | undefined {
+  if (data === undefined) return undefined;
+  if (typeof data === 'string') return { __renderLambda: true, handle: data, retentive: false };
+  return data;
+}
+
+/**
+ * Takes universal config, and converts it into latest config structure.
+ *
+ * **Important**: This operation is not meant to be executed recusively.
+ *                In no circumstance result of this function should be persisted!
+ * */
+export function extractConfigGeneric(cfg: BlockConfigContainer): BlockConfigGeneric {
+  if (cfg.v3 !== undefined) {
+    // version 3
+    const {
+      initialArgs,
+      initialUiState,
+      inputsValid,
+      outputs,
+      renderingMode,
+      sdkVersion,
+      featureFlags,
+      sections,
+      title,
+      enrichmentTargets,
+    } = cfg.v3;
+    const { code } = cfg;
+    return {
+      initialArgs,
+      initialUiState,
+      inputsValid,
+      outputs,
+      renderingMode,
+      sdkVersion,
+      featureFlags,
+      sections,
+      title,
+      code,
+      enrichmentTargets,
+    };
+  } else if (cfg.inputsValid !== undefined) {
+    // version 2
+    const { sdkVersion, renderingMode, outputs, inputsValid, sections, initialArgs, code } = cfg;
+    const fields = Object.keys(cfg);
+    if (
+      sdkVersion === undefined
+      || renderingMode === undefined
+      || outputs === undefined
+      || inputsValid === undefined
+      || sections === undefined
+      || initialArgs === undefined
+    )
+      throw new Error(
+        `Malformed config v2. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`,
+      );
+    return {
+      sdkVersion,
+      renderingMode,
+      initialArgs,
+      outputs: Object.fromEntries(
+        Object.entries(outputs).map(([key, value]) => [key, upgradeCfgOrLambda(value)]),
+      ),
+      inputsValid: upgradeCfgOrLambda(inputsValid),
+      sections: upgradeCfgOrLambda(sections),
+      initialUiState: undefined,
+      code,
+    };
+  } else if (cfg.renderingMode !== undefined) {
+    // version 1
+    const { sdkVersion, canRun, renderingMode, outputs, sections, initialArgs, code } = cfg;
+    const fields = Object.keys(cfg);
+    if (
+      renderingMode === undefined
+      || outputs === undefined
+      || canRun === undefined
+      || sections === undefined
+      || initialArgs === undefined
+    )
+      throw new Error(
+        `Malformed config v1. SDK version ${sdkVersion}; Fields = ${fields.join(', ')}`,
+      );
+    return {
+      sdkVersion: sdkVersion ?? 'unknown',
+      renderingMode,
+      initialArgs,
+      outputs: Object.fromEntries(
+        Object.entries(outputs).map(([key, value]) => [key, upgradeCfgOrLambda(value)]),
+      ),
+      inputsValid: upgradeCfgOrLambda(canRun),
+      sections: upgradeCfgOrLambda(sections),
+      initialUiState: undefined,
+      code,
+    };
+  } else {
+    const { sdkVersion } = cfg;
+    const fields = Object.keys(cfg);
+    throw new Error(
+      `Config format not supported: SDK = ${sdkVersion}; Fields = ${fields.join(', ')}`,
+    );
+  }
+}

package/src/drivers/pframe/table_calculate.ts

@@ -339,6 +339,9 @@ export interface PTableDef<Col> {
   /** Join tree to populate the PTable */
   readonly src: JoinEntry<Col>;
 
+  /** Partition filters */
+  readonly partitionFilters: PTableRecordSingleValueFilterV2[];
+
   /** Record filters */
   readonly filters: PTableRecordFilter[];
 
@@ -347,7 +350,16 @@ export interface PTableDef<Col> {
 }
 
 /** Request to create and retrieve entirety of data of PTable. */
-export type CalculateTableDataRequest<Col> = PTableDef<Col>;
+export type CalculateTableDataRequest<Col> = {
+  /** Join tree to populate the PTable */
+  readonly src: JoinEntry<Col>;
+
+  /** Record filters */
+  readonly filters: PTableRecordFilter[];
+
+  /** Table sorting */
+  readonly sorting: PTableSorting[];
+};
 
 /** Response for {@link CalculateTableDataRequest} */
 export type CalculateTableDataResponse = FullPTableColumnData[];

package/src/drivers/pframe/table_common.ts

@@ -26,3 +26,18 @@ export type PTableColumnIdColumn = {
 
 /** Unified PTable column identifier */
 export type PTableColumnId = PTableColumnIdAxis | PTableColumnIdColumn;
+
+export function getPTableColumnId(spec: PTableColumnSpec): PTableColumnId {
+  switch (spec.type) {
+    case 'axis':
+      return {
+        type: 'axis',
+        id: spec.id,
+      };
+    case 'column':
+      return {
+        type: 'column',
+        id: spec.id,
+      };
+  }
+}

package/src/flags/block_flags.ts

@@ -0,0 +1,43 @@
+import type { ArrayTypeUnion, Assert, Is, IsSubtypeOf } from './type_utils';
+
+/**
+ * Block-specific feature flags. Define flags that are interpreted by the desktop app to select
+ * appropriate API to expose into Model and UI runtimes.
+ *
+ * Flags are split into two categories:
+ *   - supports... - those flags tells the desktop app that the block supports certain APIs, but can without them as well
+ *   - requires... - those flags tells the desktop app that the block requires certain APIs, and if desktop app doesn't support it, it can't be used in the block
+ */
+export type BlockCodeFeatureFlags = Record<`supports${string}`, boolean | number | undefined> & Record<`requires${string}`, boolean | number | undefined>;
+
+/**
+ * Known block flags. Flags are set during model compilation, see `BlockModel.create` for more details and for initial values.
+ */
+export type BlockCodeKnownFeatureFlags = {
+  readonly supportsLazyState?: boolean;
+  readonly requiresModelAPIVersion?: number;
+  readonly requiresUIAPIVersion?: number;
+};
+
+export const AllSupportsFeatureFlags
+  = ['supportsLazyState'] as const;
+
+export const AllRequiresFeatureFlags
+  = ['requiresUIAPIVersion', 'requiresModelAPIVersion'] as const;
+
+//
+// Assertions
+//
+
+// This assertion ensures that BlockConfigV3KnownFeatureFlags is a subtype of BlockConfigV3FeatureFlags.
+// It will produce a compile-time error if there's a mismatch.
+type _KnownFlagsAreValidFlags = Assert<IsSubtypeOf<BlockCodeKnownFeatureFlags, BlockCodeFeatureFlags>>;
+
+// This check ensures that all keys in BlockConfigV3FeatureFlags are covered in the arrays above.
+// It will produce a compile-time error if there's a mismatch.
+type _AllFlagsAreCovered = Assert<
+  Is<
+    keyof BlockCodeKnownFeatureFlags,
+    ArrayTypeUnion<typeof AllRequiresFeatureFlags, typeof AllSupportsFeatureFlags>
+  >
+>;

package/src/flags/flag_utils.test.ts

@@ -0,0 +1,162 @@
+import { describe, it, expect } from 'vitest';
+import { RuntimeCapabilities, IncompatibleFlagsError } from './flag_utils';
+import type { BlockCodeFeatureFlags } from './block_flags';
+
+describe('RuntimeCapabilities', () => {
+  describe('addSupportedRequirement', () => {
+    it('should add a supported requirement with default value true', () => {
+      const capabilities = new RuntimeCapabilities();
+      capabilities.addSupportedRequirement('requiresModelAPIVersion');
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: true };
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+    });
+
+    it('should add a supported requirement with a specific boolean value', () => {
+        const capabilities = new RuntimeCapabilities();
+        capabilities.addSupportedRequirement('requiresModelAPIVersion', false);
+        const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: false };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+        const blockFlags2: BlockCodeFeatureFlags = { requiresModelAPIVersion: true };
+        expect(capabilities.checkCompatibility(blockFlags2)).toBe(false);
+    });
+
+    it('should add a supported requirement with a specific number value', () => {
+        const capabilities = new RuntimeCapabilities();
+        capabilities.addSupportedRequirement('requiresModelAPIVersion', 2);
+        const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: 2 };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+        const blockFlags2: BlockCodeFeatureFlags = { requiresModelAPIVersion: 3 };
+        expect(capabilities.checkCompatibility(blockFlags2)).toBe(false);
+    });
+
+    it('should allow chaining', () => {
+        const capabilities = new RuntimeCapabilities();
+        capabilities.addSupportedRequirement('requiresModelAPIVersion').addSupportedRequirement('requiresUIAPIVersion');
+        const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: true, requiresUIAPIVersion: true };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+    });
+
+    it('should support multiple values for the same requirement', () => {
+      const capabilities = new RuntimeCapabilities();
+      capabilities.addSupportedRequirement('requiresModelAPIVersion', 2);
+      capabilities.addSupportedRequirement('requiresModelAPIVersion', 3);
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: 2 };
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+      const blockFlags2: BlockCodeFeatureFlags = { requiresModelAPIVersion: 3 };
+      expect(capabilities.checkCompatibility(blockFlags2)).toBe(true);
+      const blockFlags3: BlockCodeFeatureFlags = { requiresModelAPIVersion: 4 };
+      expect(capabilities.checkCompatibility(blockFlags3)).toBe(false);
+    });
+  });
+
+  describe('checkCompatibility and getIncompatibleFlags', () => {
+    it('should return compatible for undefined flags', () => {
+      const capabilities = new RuntimeCapabilities();
+      expect(capabilities.checkCompatibility(undefined)).toBe(true);
+      expect(capabilities.getIncompatibleFlags(undefined)).toBeUndefined();
+    });
+
+    it('should return compatible for empty flags object', () => {
+      const capabilities = new RuntimeCapabilities();
+      expect(capabilities.checkCompatibility({})).toBe(true);
+      expect(capabilities.getIncompatibleFlags({})).toBeUndefined();
+    });
+
+    it('should be compatible if requirements are met', () => {
+      const capabilities = new RuntimeCapabilities()
+        .addSupportedRequirement('requiresModelAPIVersion')
+        .addSupportedRequirement('requiresUIAPIVersion', 2);
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: true, requiresUIAPIVersion: 2, supportsSomething: true };
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+      expect(capabilities.getIncompatibleFlags(blockFlags)).toBeUndefined();
+    });
+
+    it('should be incompatible if a requirement value is not met', () => {
+        const capabilities = new RuntimeCapabilities().addSupportedRequirement('requiresModelAPIVersion', 2);
+        const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: 3 };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(false);
+        const incompatible = capabilities.getIncompatibleFlags(blockFlags);
+        expect(incompatible).toEqual(new Map([['requiresModelAPIVersion', 3]]));
+    });
+
+    it('should be incompatible if a requirement is not specified in runtime capabilities', () => {
+      const capabilities = new RuntimeCapabilities();
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: true };
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(false);
+      const incompatible = capabilities.getIncompatibleFlags(blockFlags);
+      expect(incompatible).toEqual(new Map([['requiresModelAPIVersion', true]]));
+    });
+
+    it('should correctly identify multiple incompatible flags', () => {
+      const capabilities = new RuntimeCapabilities()
+        .addSupportedRequirement('requiresModelAPIVersion', true)
+        .addSupportedRequirement('requiresUIAPIVersion', 2);
+
+      const blockFlags: BlockCodeFeatureFlags = {
+        requiresModelAPIVersion: false,
+        requiresUIAPIVersion: 3,
+        requiresSomethingElse: true,
+      };
+
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(false);
+      const incompatible = capabilities.getIncompatibleFlags(blockFlags);
+      expect(incompatible).toEqual(new Map<string, number | boolean>([
+        ['requiresModelAPIVersion', false],
+        ['requiresUIAPIVersion', 3],
+        ['requiresSomethingElse', true],
+      ]));
+    });
+
+    it('should ignore non-requirement flags', () => {
+        const capabilities = new RuntimeCapabilities();
+        const blockFlags: BlockCodeFeatureFlags = { supportsSomething: true };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+        expect(capabilities.getIncompatibleFlags(blockFlags)).toBeUndefined();
+    });
+
+    it('should ignore undefined requirement flags in block', () => {
+        const capabilities = new RuntimeCapabilities();
+        const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: undefined };
+        expect(capabilities.checkCompatibility(blockFlags)).toBe(true);
+        expect(capabilities.getIncompatibleFlags(blockFlags)).toBeUndefined();
+    });
+
+    it('should be incompatible if a requirement is not defined in capabilities', () => {
+      const capabilities = new RuntimeCapabilities(); // No requirements added.
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: 1 };
+      expect(capabilities.checkCompatibility(blockFlags)).toBe(false);
+      const incompatible = capabilities.getIncompatibleFlags(blockFlags);
+      expect(incompatible).toEqual(new Map([['requiresModelAPIVersion', 1]]));
+    });
+  });
+
+  describe('throwIfIncompatible', () => {
+    it('should not throw if flags are compatible', () => {
+      const capabilities = new RuntimeCapabilities().addSupportedRequirement('requiresModelAPIVersion');
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: true };
+      expect(() => capabilities.throwIfIncompatible(blockFlags)).not.toThrow();
+    });
+
+    it('should throw IncompatibleFlagsError if flags are incompatible', () => {
+      const capabilities = new RuntimeCapabilities().addSupportedRequirement('requiresModelAPIVersion');
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: false };
+      expect(() => capabilities.throwIfIncompatible(blockFlags)).toThrow(IncompatibleFlagsError);
+    });
+
+    it('should throw with an error containing incompatible flags', () => {
+      const capabilities = new RuntimeCapabilities().addSupportedRequirement('requiresModelAPIVersion', 1);
+      const blockFlags: BlockCodeFeatureFlags = { requiresModelAPIVersion: 2 };
+      try {
+        capabilities.throwIfIncompatible(blockFlags);
+        // fail test if it doesn't throw
+        expect(true).toBe(false);
+      } catch (e) {
+        expect(e).toBeInstanceOf(IncompatibleFlagsError);
+        if (e instanceof IncompatibleFlagsError) {
+          expect(e.incompatibleFlags).toEqual(new Map([['requiresModelAPIVersion', 2]]));
+          expect(e.message).toContain('requiresModelAPIVersion: 2');
+        }
+      }
+    });
+  });
+});

package/src/flags/flag_utils.ts

@@ -0,0 +1,104 @@
+import type { BlockCodeFeatureFlags, BlockCodeKnownFeatureFlags } from './block_flags';
+import type { FilterKeysByPrefix } from './type_utils';
+
+export function checkBlockFlag(flags: BlockCodeFeatureFlags | undefined, flag: keyof BlockCodeKnownFeatureFlags, flagValue: boolean | number = true): boolean {
+  if (flags === undefined) return false;
+  return flags[flag] === flagValue;
+}
+
+/**
+   * Extracts all requirements from the feature flags.
+   * @param flags - The feature flags.
+   * @returns A set of requirements.
+   */
+export function extractAllRequirements(flags: BlockCodeFeatureFlags | undefined): Set<`requires${string}`> {
+  if (flags === undefined) return new Set();
+  return new Set(Object.entries(flags)
+    .filter(([key, value]) => key.startsWith('requires') && value === true)
+    .map(([key]) => key as `requires${string}`));
+}
+
+/**
+   * Extracts all supports from the feature flags.
+   * @param flags - The feature flags.
+   * @returns A set of supports.
+   */
+export function extractAllSupports(flags: BlockCodeFeatureFlags | undefined): Set<`supports${string}`> {
+  if (flags === undefined) return new Set();
+  return new Set(Object.entries(flags)
+    .filter(([key, value]) => key.startsWith('supports') && value === true)
+    .map(([key]) => key as `supports${string}`));
+}
+
+export class IncompatibleFlagsError extends Error {
+  name = 'IncompatibleFlagsError';
+  constructor(public readonly incompatibleFlags: Map<`requires${string}`, number | boolean>) {
+    super(`Some of the block requirements are not supported by the runtime: ${Array.from(incompatibleFlags.entries()).map(([key, value]) => `${key}: ${value}`).join(', ')}`);
+  }
+}
+
+/**
+   * A type that represents a supported requirement.
+   * @remarks
+   * This type is used to represent a supported requirement.
+   * It is a subtype of `BlockCodeKnownFeatureFlags` and is used to represent a supported requirement.
+   * It is used to represent a supported requirement.
+   */
+export type SupportedRequirement = FilterKeysByPrefix<BlockCodeKnownFeatureFlags, 'requires'>;
+
+export class RuntimeCapabilities {
+  private readonly supportedRequirements: Map<`requires${string}`, Set<number | boolean>> = new Map();
+
+  /**
+     * Adds a supported requirement to the runtime capabilities.
+     * @param requirement - The requirement.
+     * @param value - The value of the requirement. If not provided, defaults to true.
+     */
+  public addSupportedRequirement(requirement: SupportedRequirement, value: number | boolean = true): this {
+    if (!this.supportedRequirements.has(requirement)) {
+      this.supportedRequirements.set(requirement, new Set());
+    }
+    this.supportedRequirements.get(requirement)!.add(value);
+    return this;
+  }
+
+  /**
+     * Returns a map of incompatible flags. If the block flags are compatible, returns undefined.
+     * @param blockFlags - The block flags.
+     * @returns A map of incompatible flags, or undefined if the block flags are compatible.
+     */
+  public getIncompatibleFlags(blockFlags: BlockCodeFeatureFlags | undefined): Map<`requires${string}`, number | boolean> | undefined {
+    if (blockFlags === undefined) return undefined;
+    const incompatibleFlags = new Map<`requires${string}`, number | boolean>();
+    for (const [key, value] of Object.entries(blockFlags)) {
+      if (key.startsWith('requires')) {
+        if (value === undefined) continue;
+        const supportedValues = this.supportedRequirements.get(key as `requires${string}`);
+        if (supportedValues === undefined || !supportedValues.has(value as number | boolean)) {
+          incompatibleFlags.set(key as `requires${string}`, value as number | boolean);
+        }
+      }
+    }
+    return incompatibleFlags.size === 0 ? undefined : incompatibleFlags;
+  }
+
+  /**
+     * Checks if the block flags are compatible with the runtime capabilities.
+     * @param blockFlags - The block flags.
+     * @returns True if the block flags are compatible, false otherwise.
+     */
+  public checkCompatibility(blockFlags: BlockCodeFeatureFlags | undefined): boolean {
+    return this.getIncompatibleFlags(blockFlags) === undefined;
+  }
+
+  /**
+     * Throws an error if the block flags are incompatible with the runtime capabilities.
+     * @param blockFlags - The block flags.
+     * @throws IncompatibleFlagsError if the block flags are incompatible with the runtime capabilities.
+     */
+  public throwIfIncompatible(blockFlags: BlockCodeFeatureFlags | undefined) {
+    const incompatibleFlags = this.getIncompatibleFlags(blockFlags);
+    if (incompatibleFlags !== undefined)
+      throw new IncompatibleFlagsError(incompatibleFlags);
+  }
+}

package/src/flags/index.ts

@@ -0,0 +1,3 @@
+export * from './block_flags';
+export * from './flag_utils';
+export * from './type_utils';

package/src/flags/type_utils.ts

@@ -0,0 +1,43 @@
+/**
+ * Helper to filter keys of a type by a prefix.
+ */
+export type FilterKeysByPrefix<T, P extends string> = keyof {
+  [K in keyof T as K extends `${P}${string}` ? K : never]: T[K];
+};
+
+/**
+ * Helper to assert that two types are equal. This will cause a compile-time error if they are not.
+ * We use this to ensure all feature flags are accounted for in the arrays below.
+ */
+export type AssertKeysEqual<T, U> = (<V>() => V extends T ? 1 : 2) extends <V>() => V extends U ? 1 : 2
+  ? unknown
+  : { error: 'Feature flag definitions are out of sync'; expected: T; actual: U };
+
+/**
+ * Checks if two types are exactly equal.
+ * Returns 'true' if they are, 'false' otherwise.
+ */
+export type Is<T, U> = (<G>() => G extends T ? 1 : 2) extends <G>() => G extends U ? 1 : 2
+  ? true
+  : false;
+
+/**
+ * Checks if T is a subtype of U.
+ * Returns 'true' if it is, 'false' otherwise.
+ */
+export type IsSubtypeOf<T, U> = T extends U ? true : false;
+
+/**
+ * Asserts that a condition is true at compile time.
+ * Causes a compile error if T is not 'true'.
+ */
+export type Assert<T extends true> = T;
+
+/**
+ * Helper to create a union type of two array value types.
+ */
+export type ArrayTypeUnion<T extends readonly any[], U extends readonly any[]> = T[number] extends never
+  ? U[number]
+  : U[number] extends never
+    ? T[number]
+    : T[number] | U[number];