feat(entity): support polymorphic-table cascades via additionalFieldFilters

## Summary

Adds an optional `additionalFieldFilters` field on `EntityAssociationDefinition` that AND's extra field-equality conditions onto the cascade load when the source entity is deleted. This lets polymorphic child tables — multiple entity classes backed by one DB table and distinguished by scope-specific columns — register each class with a scope-disambiguating filter so cascade loads through one class never see rows that belong to a sibling class (which would otherwise trip the wrong-scope constructor invariant and abort the entire cascade).

## Motivation

For polymorphic tables where multiple entity classes share a table and each enforces a scope-specific constructor invariant (e.g. `TurtleJobRunEntity` requires `appId !== null`, `AccountTurtleJobRunEntity` requires `accountId !== null`), the parent-delete cascade currently loads every row matching the foreign key regardless of scope. Loading mixed-scope rows through one class throws on the wrong-scope rows and aborts the cascade. Consumers had to work around this with helper functions; this PR makes the scope filter expressible in the association config itself.

## Mechanism

- New `FieldEqualityCondition` types live in the base `@expo/entity` package (re-exported from `@expo/entity-database-adapter-knex` for back-compat).
- New `fetchManyByFieldEqualityConjunctionAsync` on the base `EntityDatabaseAdapter` with a default impl that uses single-value operands for the SQL WHERE and applies multi-value operands as an in-memory filter. The knex adapter overrides it for native SQL conjunction filtering (with proper `IS NULL` semantics).
- New `loadManyByFieldEqualityConjunctionAsync` on both `AuthorizationResultBasedEntityLoader` and `EnforcingEntityLoader`.
- The cascade in `AuthorizationResultBasedEntityMutator.processEntityDeletionForInboundEdgesAsync` builds `[{ primary }, ...association.additionalFieldFilters]` and calls the new loader method. All four `EntityEdgeDeletionBehavior` branches benefit automatically.
- `additionalFieldFilters` is typed via a new `TSourceFields` generic threaded through `EntityFieldDefinition`, its options, and `EntityConfiguration.schema`, so filter field names are type-checked against the source entity's `TFields` at the schema literal.
- No behavior change for associations that don't set `additionalFieldFilters` — the cascade load is equivalent to the previous single-equality load.

## Related

- Original consumer motivation: expo/universe#27183
- Prototype helper in consumer code: expo/universe#27406

## Test plan

- [x] `yarn tsc`
- [x] `yarn lint`
- [x] `yarn test` — 735 unit tests, including 4 new in `EntityEdgesAdditionalFieldFilters-test.ts` covering: no-filter regression, polymorphic scope filters, multi-row cascade, no-op filter
- [x] `yarn integration` — 123 integration tests, including 2 new in `EntityEdgesAdditionalFieldFiltersIntegration-test.ts` exercising the native SQL conjunction path against Postgres

Author: szdziedzic

packages/entity-database-adapter-knex/src/AuthorizationResultBasedKnexEntityLoader.ts

@@ -2,18 +2,15 @@ import type {
   EntityConstructionUtils,
   EntityPrivacyPolicy,
   EntityQueryContext,
+  FieldEqualityCondition,
   IEntityMetricsAdapter,
   ReadonlyEntity,
   ViewerContext,
 } from '@expo/entity';
+import { isSingleValueFieldEqualityCondition } from '@expo/entity';
 import type { Result } from '@expo/results';
 
-import type {
-  FieldEqualityCondition,
-  NullsOrdering,
-  OrderByOrdering,
-} from './BasePostgresEntityDatabaseAdapter.ts';
-import { isSingleValueFieldEqualityCondition } from './BasePostgresEntityDatabaseAdapter.ts';
+import type { NullsOrdering, OrderByOrdering } from './BasePostgresEntityDatabaseAdapter.ts';
 import { BaseSQLQueryBuilder } from './BaseSQLQueryBuilder.ts';
 import type { PaginationStrategy } from './PaginationStrategy.ts';
 import type { SQLFragment } from './SQLOperator.ts';

packages/entity-database-adapter-knex/src/BasePostgresEntityDatabaseAdapter.ts

@@ -1,53 +1,14 @@
-import type { EntityQueryContext } from '@expo/entity';
+import type { EntityQueryContext, FieldEqualityCondition } from '@expo/entity';
 import {
   EntityDatabaseAdapter,
   getDatabaseFieldForEntityField,
+  isSingleValueFieldEqualityCondition,
   transformDatabaseObjectToFields,
 } from '@expo/entity';
 import type { Knex } from 'knex';
 
 import type { SQLFragment } from './SQLOperator.ts';
 
-/**
- * Equality operand that is used for selecting entities with a field with a single value.
- */
-export interface SingleValueFieldEqualityCondition<
-  TFields extends Record<string, any>,
-  N extends keyof TFields = keyof TFields,
-> {
-  fieldName: N;
-  fieldValue: TFields[N];
-}
-
-/**
- * Equality operand that is used for selecting entities with a field matching one of multiple values.
- */
-export interface MultiValueFieldEqualityCondition<
-  TFields extends Record<string, any>,
-  N extends keyof TFields = keyof TFields,
-> {
-  fieldName: N;
-  fieldValues: readonly TFields[N][];
-}
-
-/**
- * A single equality operand for use in a selection clause.
- * See EntityLoader.loadManyByFieldEqualityConjunctionAsync documentation for examples.
- */
-export type FieldEqualityCondition<
-  TFields extends Record<string, any>,
-  N extends keyof TFields = keyof TFields,
-> = SingleValueFieldEqualityCondition<TFields, N> | MultiValueFieldEqualityCondition<TFields, N>;
-
-export function isSingleValueFieldEqualityCondition<
-  TFields extends Record<string, any>,
-  N extends keyof TFields = keyof TFields,
->(
-  condition: FieldEqualityCondition<TFields, N>,
-): condition is SingleValueFieldEqualityCondition<TFields, N> {
-  return (condition as SingleValueFieldEqualityCondition<TFields, N>).fieldValue !== undefined;
-}
-
 export interface TableFieldSingleValueEqualityCondition {
   tableField: string;
   tableValue: any;
@@ -167,17 +128,19 @@ export abstract class BasePostgresEntityDatabaseAdapter<
   }
   /**
    * Fetch many objects matching the conjunction of where clauses constructed from
-   * specified field equality operands.
+   * specified field equality operands. Overrides the base entity adapter implementation
+   * to push the conjunction filter all the way down to SQL.
    *
    * @param queryContext - query context with which to perform the fetch
    * @param fieldEqualityOperands - list of field equality where clause operand specifications
-   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query
+   * @param querySelectionModifiers - limit, offset, orderBy, and orderByRaw for the query.
+   *   Optional; when omitted the entire conjunction is returned in arbitrary order.
    * @returns array of objects matching the query
    */
-  async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
+  override async fetchManyByFieldEqualityConjunctionAsync<N extends keyof TFields>(
     queryContext: EntityQueryContext,
     fieldEqualityOperands: readonly FieldEqualityCondition<TFields, N>[],
-    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields>,
+    querySelectionModifiers: PostgresQuerySelectionModifiers<TFields> = {},
   ): Promise<readonly Readonly<TFields>[]> {
     const tableFieldSingleValueOperands: TableFieldSingleValueEqualityCondition[] = [];
     const tableFieldMultipleValueOperands: TableFieldMultiValueEqualityCondition[] = [];

packages/entity-database-adapter-knex/src/EnforcingKnexEntityLoader.ts

@@ -2,6 +2,7 @@ import type {
   EntityConstructionUtils,
   EntityPrivacyPolicy,
   EntityQueryContext,
+  FieldEqualityCondition,
   IEntityMetricsAdapter,
   ReadonlyEntity,
   ViewerContext,
@@ -12,7 +13,6 @@ import type {
   EntityLoaderLoadPageArgs,
   EntityLoaderQuerySelectionModifiers,
 } from './AuthorizationResultBasedKnexEntityLoader.ts';
-import type { FieldEqualityCondition } from './BasePostgresEntityDatabaseAdapter.ts';
 import { BaseSQLQueryBuilder } from './BaseSQLQueryBuilder.ts';
 import type { SQLFragment } from './SQLOperator.ts';
 import type { Connection, EntityKnexDataManager } from './internal/EntityKnexDataManager.ts';

packages/entity-database-adapter-knex/src/EntityFields.ts

@@ -3,10 +3,10 @@ import { EntityFieldDefinition } from '@expo/entity';
 /**
  * EntityFieldDefinition for a Postres column with a JS JSON array type.
  */
-export class JSONArrayField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
-  any[],
-  TRequireExplicitCache
-> {
+export class JSONArrayField<
+  TRequireExplicitCache extends boolean,
+  TSourceFields extends Record<string, any> = any,
+> extends EntityFieldDefinition<any[], TRequireExplicitCache, TSourceFields> {
   protected validateInputValueInternal(value: any[]): boolean {
     return Array.isArray(value);
   }
@@ -18,7 +18,8 @@ export class JSONArrayField<TRequireExplicitCache extends boolean> extends Entit
  */
 export class MaybeJSONArrayField<
   TRequireExplicitCache extends boolean,
-> extends EntityFieldDefinition<any | any[], TRequireExplicitCache> {
+  TSourceFields extends Record<string, any> = any,
+> extends EntityFieldDefinition<any | any[], TRequireExplicitCache, TSourceFields> {
   protected validateInputValueInternal(_value: any): boolean {
     return true;
   }
@@ -27,10 +28,10 @@ export class MaybeJSONArrayField<
 /**
  * EntityFieldDefinition for a Postgres BIGINT column.
  */
-export class BigIntField<TRequireExplicitCache extends boolean> extends EntityFieldDefinition<
-  string,
-  TRequireExplicitCache
-> {
+export class BigIntField<
+  TRequireExplicitCache extends boolean,
+  TSourceFields extends Record<string, any> = any,
+> extends EntityFieldDefinition<string, TRequireExplicitCache, TSourceFields> {
   protected validateInputValueInternal(value: string): boolean {
     return typeof value === 'string';
   }

packages/entity-database-adapter-knex/src/internal/EntityKnexDataManager.ts

@@ -1,4 +1,9 @@
-import type { EntityConfiguration, EntityQueryContext, IEntityMetricsAdapter } from '@expo/entity';
+import type {
+  EntityConfiguration,
+  EntityQueryContext,
+  FieldEqualityCondition,
+  IEntityMetricsAdapter,
+} from '@expo/entity';
 import {
   EntityDatabaseAdapterPaginationCursorInvalidError,
   EntityMetricsLoadType,
@@ -10,7 +15,6 @@ import assert from 'assert';
 
 import type {
   BasePostgresEntityDatabaseAdapter,
-  FieldEqualityCondition,
   PostgresOrderByClause,
   PostgresQuerySelectionModifiers,
 } from '../BasePostgresEntityDatabaseAdapter.ts';

packages/entity-full-integration-tests/src/__integration-tests__/EntityEdgesAdditionalFieldFiltersIntegration-test.ts

@@ -0,0 +1,140 @@
+import { ViewerContext } from '@expo/entity';
+import type { GenericRedisCacheContext } from '@expo/entity-cache-adapter-redis';
+import { RedisCacheInvalidationStrategy } from '@expo/entity-cache-adapter-redis';
+import nullthrows from '@expo/nullthrows';
+import { afterAll, beforeAll, beforeEach, describe, expect, it } from '@jest/globals';
+import { Redis } from 'ioredis';
+import type { Knex } from 'knex';
+import knex from 'knex';
+import { URL } from 'url';
+
+import { createFullIntegrationTestEntityCompanionProvider } from '../__testfixtures__/createFullIntegrationTestEntityCompanionProvider.ts';
+import PolyParentEntity from './entities/PolyParentEntity.ts';
+import ScopeAChildEntity from './entities/ScopeAChildEntity.ts';
+import ScopeBChildEntity from './entities/ScopeBChildEntity.ts';
+
+async function createPostgresTablesAsync(knex: Knex): Promise<void> {
+  await knex.schema.createTable('poly_parents', (table) => {
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
+  });
+  await knex.schema.createTable('poly_children', (table) => {
+    table.uuid('id').defaultTo(knex.raw('gen_random_uuid()')).primary();
+    table.uuid('parent_id').references('id').inTable('poly_parents');
+    table.string('scope').notNullable();
+  });
+}
+
+async function truncatePostgresTablesAsync(knex: Knex): Promise<void> {
+  await knex.raw('TRUNCATE TABLE poly_children, poly_parents CASCADE');
+}
+
+async function dropPostgresTablesAsync(knex: Knex): Promise<void> {
+  if (await knex.schema.hasTable('poly_children')) {
+    await knex.schema.dropTable('poly_children');
+  }
+  if (await knex.schema.hasTable('poly_parents')) {
+    await knex.schema.dropTable('poly_parents');
+  }
+}
+
+describe('EntityMutator.processEntityDeletionForInboundEdgesAsync with additionalFieldFilters', () => {
+  let knexInstance: Knex;
+  const redisClient = new Redis(new URL(process.env['REDIS_URL']!).toString());
+  let genericRedisCacheContext: GenericRedisCacheContext;
+
+  beforeAll(async () => {
+    knexInstance = knex({
+      client: 'pg',
+      connection: {
+        user: nullthrows(process.env['PGUSER']),
+        password: nullthrows(process.env['PGPASSWORD']),
+        host: 'localhost',
+        port: parseInt(nullthrows(process.env['PGPORT']), 10),
+        database: nullthrows(process.env['PGDATABASE']),
+      },
+    });
+    genericRedisCacheContext = {
+      redisClient,
+      makeKeyFn(...parts: string[]): string {
+        const delimiter = ':';
+        const escapedParts = parts.map((part) =>
+          part.replaceAll('\\', '\\\\').replaceAll(delimiter, `\\${delimiter}`),
+        );
+        return escapedParts.join(delimiter);
+      },
+      cacheKeyPrefix: 'test-',
+      ttlSecondsPositive: 86400,
+      ttlSecondsNegative: 600,
+      invalidationConfig: {
+        invalidationStrategy: RedisCacheInvalidationStrategy.CURRENT_CACHE_KEY_VERSION,
+      },
+    };
+    await createPostgresTablesAsync(knexInstance);
+  });
+
+  beforeEach(async () => {
+    await truncatePostgresTablesAsync(knexInstance);
+    await redisClient.flushdb();
+  });
+
+  afterAll(async () => {
+    await dropPostgresTablesAsync(knexInstance);
+    await knexInstance.destroy();
+    redisClient.disconnect();
+  });
+
+  it('cascade-deletes only rows matching the additionalFieldFilters of each association', async () => {
+    const viewerContext = new ViewerContext(
+      createFullIntegrationTestEntityCompanionProvider(knexInstance, genericRedisCacheContext),
+    );
+
+    const parent = await PolyParentEntity.creator(viewerContext).createAsync();
+    const scopeARow = await ScopeAChildEntity.creator(viewerContext)
+      .setField('parent_id', parent.getID())
+      .setField('scope', 'A')
+      .createAsync();
+    const scopeBRow = await ScopeBChildEntity.creator(viewerContext)
+      .setField('parent_id', parent.getID())
+      .setField('scope', 'B')
+      .createAsync();
+
+    await expect(
+      ScopeAChildEntity.loader(viewerContext).loadByIDNullableAsync(scopeARow.getID()),
+    ).resolves.not.toBeNull();
+    await expect(
+      ScopeBChildEntity.loader(viewerContext).loadByIDNullableAsync(scopeBRow.getID()),
+    ).resolves.not.toBeNull();
+
+    // Without per-class scope filters in the inbound-edge associations, the cascade would
+    // load every scope-A and scope-B row through each class and trip the wrong-scope
+    // constructor invariant. The additionalFieldFilters narrow each cascade load to the
+    // single matching scope.
+    await PolyParentEntity.deleter(parent).deleteAsync();
+
+    await expect(
+      ScopeAChildEntity.loader(viewerContext).loadByIDNullableAsync(scopeARow.getID()),
+    ).resolves.toBeNull();
+    await expect(
+      ScopeBChildEntity.loader(viewerContext).loadByIDNullableAsync(scopeBRow.getID()),
+    ).resolves.toBeNull();
+  });
+
+  it('is a no-op for an association whose filter matches no rows', async () => {
+    const viewerContext = new ViewerContext(
+      createFullIntegrationTestEntityCompanionProvider(knexInstance, genericRedisCacheContext),
+    );
+
+    const parent = await PolyParentEntity.creator(viewerContext).createAsync();
+    const scopeARow = await ScopeAChildEntity.creator(viewerContext)
+      .setField('parent_id', parent.getID())
+      .setField('scope', 'A')
+      .createAsync();
+    // No scope=B rows; the ScopeB association load returns zero rows.
+
+    await PolyParentEntity.deleter(parent).deleteAsync();
+
+    await expect(
+      ScopeAChildEntity.loader(viewerContext).loadByIDNullableAsync(scopeARow.getID()),
+    ).resolves.toBeNull();
+  });
+});

packages/entity-full-integration-tests/src/__integration-tests__/entities/PolyParentEntity.ts

@@ -0,0 +1,58 @@
+import type { EntityCompanionDefinition, ViewerContext } from '@expo/entity';
+import {
+  AlwaysAllowPrivacyPolicyRule,
+  Entity,
+  EntityConfiguration,
+  EntityPrivacyPolicy,
+  UUIDField,
+} from '@expo/entity';
+
+import ScopeAChildEntity from './ScopeAChildEntity.ts';
+import ScopeBChildEntity from './ScopeBChildEntity.ts';
+
+interface PolyParentFields {
+  id: string;
+}
+
+class TestEntityPrivacyPolicy extends EntityPrivacyPolicy<any, 'id', ViewerContext, any, any> {
+  protected override readonly readRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, 'id', ViewerContext, any, any>(),
+  ];
+  protected override readonly createRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, 'id', ViewerContext, any, any>(),
+  ];
+  protected override readonly updateRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, 'id', ViewerContext, any, any>(),
+  ];
+  protected override readonly deleteRules = [
+    new AlwaysAllowPrivacyPolicyRule<any, 'id', ViewerContext, any, any>(),
+  ];
+}
+
+export default class PolyParentEntity extends Entity<PolyParentFields, 'id', ViewerContext> {
+  static defineCompanionDefinition(): EntityCompanionDefinition<
+    PolyParentFields,
+    'id',
+    ViewerContext,
+    PolyParentEntity,
+    TestEntityPrivacyPolicy
+  > {
+    return {
+      entityClass: PolyParentEntity,
+      entityConfiguration: new EntityConfiguration<PolyParentFields, 'id'>({
+        idField: 'id',
+        tableName: 'poly_parents',
+        inboundEdges: [ScopeAChildEntity, ScopeBChildEntity],
+        schema: {
+          id: new UUIDField({
+            columnName: 'id',
+            cache: true,
+          }),
+        },
+        databaseAdapterFlavor: 'postgres',
+        cacheAdapterFlavor: 'redis',
+      }),
+      privacyPolicyClass: TestEntityPrivacyPolicy,
+    };
+  }
+}