@nest-yalc-2/omnikernel-module 1.1.0

package/src/omni-scoped.repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"omni-scoped.repository.js","sourceRoot":"","sources":["omni-scoped.repository.ts"],"names":[],"mappings":";;;AAQA,MAAa,oBAAoB;IAC/B,YACmB,UAA8B,EAC9B,KAAgB;QADhB,eAAU,GAAV,UAAU,CAAoB;QAC9B,UAAK,GAAL,KAAK,CAAW;IAChC,CAAC;IAEJ,KAAK,CACH,QAAkC,EAA8B;QAEhE,IAAI,SAAS,IAAK,KAAgB,EAAE,CAAC;YACnC,MAAM,IAAI,SAAS,CAAC,8CAA8C,CAAC,CAAC;QACtE,CAAC;QACD,OAAO;YACL,GAAI,KAAgB;YACpB,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,OAAO;SACW,CAAC;IAC3C,CAAC;IAED,aAAa,CAAC,IAAY;QACxB,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,EAAE,IAAI,EAAW,CAAC,EAAE,CAAC,CAAC;IAC3E,CAAC;IAED,IAAI,CAAC,QAAkC,EAA8B;QACnE,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IAC5D,CAAC;CACF;AAzBD,oDAyBC"}

package/src/omni-scoped.repository.ts

@@ -0,0 +1,34 @@
+import type { FindOptionsWhere, ObjectLiteral, Repository } from 'typeorm';
+import type { OmniScope } from './omni-scope.js';
+
+/**
+ * Small repository facade for normal Omni lookups. It mechanically adds the
+ * current scope and is the supported lower-level alternative to passing raw
+ * repositories between application layers.
+ */
+export class OmniScopedRepository<Entity extends ObjectLiteral> {
+  constructor(
+    private readonly repository: Repository<Entity>,
+    private readonly scope: OmniScope,
+  ) {}
+
+  where(
+    where: FindOptionsWhere<Entity> = {} as FindOptionsWhere<Entity>,
+  ): FindOptionsWhere<Entity> {
+    if ('scopeId' in (where as object)) {
+      throw new TypeError('Omni scopeId is derived from server context.');
+    }
+    return {
+      ...(where as object),
+      scopeId: this.scope.scopeId,
+    } as unknown as FindOptionsWhere<Entity>;
+  }
+
+  findOneByGuid(guid: string): Promise<Entity | null> {
+    return this.repository.findOne({ where: this.where({ guid } as never) });
+  }
+
+  find(where: FindOptionsWhere<Entity> = {} as FindOptionsWhere<Entity>) {
+    return this.repository.find({ where: this.where(where) });
+  }
+}

package/src/omni-scoped.service.d.ts

@@ -0,0 +1,36 @@
+import type { CrudGenFindManyOptions } from '@nest-yalc-2/crud-gen/api-graphql/crud-gen-gql.interface.js';
+import { GenericService } from '@nest-yalc-2/crud-gen/typeorm/generic.service.js';
+import type { DeepPartial, FindOptionsWhere, ObjectLiteral } from 'typeorm';
+import type { OmniDeletePolicy, OmniScope } from './omni-scope.js';
+type ScopedEntity = ObjectLiteral & {
+    scopeId: string;
+    deletedAt?: Date | null;
+};
+export declare class OmniScopedService<Entity extends ScopedEntity> extends GenericService<Entity> {
+    private readonly deletion;
+    constructor(repository: any, scopeOrRepositoryWrite?: OmniScope | any, deletion?: OmniDeletePolicy);
+    protected readonly scope: OmniScope;
+    protected get scopeId(): string;
+    protected scopedConditions(conditions: FindOptionsWhere<Entity>): FindOptionsWhere<Entity>;
+    getEntity(conditions: FindOptionsWhere<Entity>[] | FindOptionsWhere<Entity> | ObjectLiteral | string, fields?: (keyof Entity)[], relations?: string[], databaseName?: string, options?: {
+        failOnNull: false;
+    }): Promise<Entity | undefined>;
+    getEntity(conditions: FindOptionsWhere<Entity>[] | FindOptionsWhere<Entity> | ObjectLiteral | string, fields?: (keyof Entity)[], relations?: string[], databaseName?: string, options?: {
+        failOnNull?: boolean;
+    }): Promise<Entity>;
+    getEntityListExtended(findOptions: CrudGenFindManyOptions<Entity>, withCount?: false, relations?: string[], databaseName?: string): Promise<Entity[]>;
+    getEntityListExtended(findOptions: CrudGenFindManyOptions<Entity>, withCount: true, relations?: string[], databaseName?: string): Promise<[Entity[], number]>;
+    private scopeFindOptions;
+    createEntity(input: DeepPartial<Entity>, findOptions?: CrudGenFindManyOptions<Entity>, returnEntity?: true): Promise<Entity>;
+    createEntity(input: DeepPartial<Entity>, findOptions?: CrudGenFindManyOptions<Entity>, returnEntity?: boolean): Promise<Entity | boolean>;
+    updateEntity(conditions: FindOptionsWhere<Entity>, input: DeepPartial<Entity>, findOptions?: CrudGenFindManyOptions<Entity>, returnEntity?: true): Promise<Entity>;
+    updateEntity(conditions: FindOptionsWhere<Entity>, input: DeepPartial<Entity>, findOptions?: CrudGenFindManyOptions<Entity>, returnEntity?: boolean): Promise<Entity | boolean>;
+    deleteEntity(conditions: FindOptionsWhere<Entity>): Promise<boolean>;
+    protected rejectServerFields(input: object): void;
+    protected rejectClientScope(input: object): void;
+    private validatePayloadContract;
+    protected notFound(): never;
+    private scopedWhere;
+    private rejectScopeInWhere;
+}
+export {};

package/src/omni-scoped.service.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OmniScopedService = void 0;
+const common_1 = require("@nestjs/common");
+const crud_gen_enum_js_1 = require("@nest-yalc-2/crud-gen/crud-gen.enum.js");
+const generic_service_js_1 = require("@nest-yalc-2/crud-gen/typeorm/generic.service.js");
+const typeorm_1 = require("typeorm");
+function hasOwn(input, key) {
+    return Object.prototype.hasOwnProperty.call(input, key);
+}
+class OmniScopedService extends generic_service_js_1.GenericService {
+    constructor(repository, scopeOrRepositoryWrite, deletion = 'hard') {
+        const scope = isOmniScope(scopeOrRepositoryWrite)
+            ? scopeOrRepositoryWrite
+            : defaultOmniScope;
+        super(repository, isOmniScope(scopeOrRepositoryWrite) ? undefined : scopeOrRepositoryWrite);
+        this.deletion = deletion;
+        this.scope = scope;
+    }
+    get scopeId() {
+        return this.scope.scopeId;
+    }
+    scopedConditions(conditions) {
+        this.rejectClientScope(conditions);
+        return {
+            ...conditions,
+            scopeId: this.scopeId,
+            ...(this.deletion === 'tombstone' ? { deletedAt: (0, typeorm_1.IsNull)() } : {}),
+        };
+    }
+    async getEntity(conditions, fields, relations, databaseName, options) {
+        const entity = await super.getEntity(this.scopedWhere(conditions), fields, relations, databaseName, { failOnNull: false });
+        if (!entity && options?.failOnNull)
+            this.notFound();
+        return entity;
+    }
+    async getEntityListExtended(findOptions = {}, withCount = false, relations, databaseName) {
+        const scopedOptions = this.scopeFindOptions(findOptions);
+        if (withCount) {
+            return super.getEntityListExtended(scopedOptions, true, relations, databaseName);
+        }
+        return super.getEntityListExtended(scopedOptions, false, relations, databaseName);
+    }
+    scopeFindOptions(findOptions) {
+        this.rejectScopeInWhere(findOptions.where);
+        const userWhere = findOptions.where;
+        const filters = {};
+        filters.scopeId = this.scopeId;
+        if (this.deletion === 'tombstone')
+            filters.deletedAt = (0, typeorm_1.IsNull)();
+        const where = {
+            operator: crud_gen_enum_js_1.Operators.AND,
+            filters,
+            ...(userWhere ? { childExpressions: [userWhere] } : {}),
+        };
+        return {
+            ...findOptions,
+            where,
+            ...(findOptions.subQueryFilters
+                ? {
+                    subQueryFilters: this.scopeFindOptions(findOptions.subQueryFilters),
+                }
+                : {}),
+        };
+    }
+    async createEntity(input, findOptions, returnEntity = true) {
+        this.rejectServerFields(input);
+        this.validatePayloadContract(input);
+        return super.createEntity({ ...input, scopeId: this.scopeId }, findOptions, returnEntity);
+    }
+    async updateEntity(conditions, input, findOptions, returnEntity = true) {
+        this.rejectServerFields(input);
+        this.validatePayloadContract(input);
+        if (hasOwn(input, 'guid')) {
+            throw new common_1.BadRequestException('guid is immutable.');
+        }
+        return super.updateEntity(this.scopedConditions(conditions), { ...input, scopeId: this.scopeId }, findOptions, returnEntity);
+    }
+    async deleteEntity(conditions) {
+        const scoped = this.scopedConditions(conditions);
+        if (this.deletion === 'hard') {
+            return super.deleteEntity(scoped);
+        }
+        const result = await this.getRepository().update(scoped, {
+            deletedAt: new Date(),
+        });
+        if (!result.affected)
+            this.notFound();
+        return true;
+    }
+    rejectServerFields(input) {
+        for (const field of ['scopeId', 'revision', 'deletedAt']) {
+            if (hasOwn(input, field)) {
+                throw new common_1.BadRequestException(`${field} is server-owned.`);
+            }
+        }
+    }
+    rejectClientScope(input) {
+        if (hasOwn(input, 'scopeId')) {
+            throw new common_1.BadRequestException('scopeId is derived from server context.');
+        }
+    }
+    validatePayloadContract(input) {
+        const candidate = input;
+        if (hasOwn(candidate, 'payload') &&
+            candidate.payload !== null &&
+            (typeof candidate.payload !== 'object' ||
+                Array.isArray(candidate.payload))) {
+            throw new common_1.BadRequestException('payload must be a JSON object or null.');
+        }
+        const hasSchemaId = hasOwn(candidate, 'payloadSchemaId');
+        const hasSchemaVersion = hasOwn(candidate, 'payloadSchemaVersion');
+        if (hasSchemaId !== hasSchemaVersion) {
+            throw new common_1.BadRequestException('payloadSchemaId and payloadSchemaVersion must be supplied together.');
+        }
+        if (!hasSchemaId)
+            return;
+        if (typeof candidate.payloadSchemaId !== 'string' ||
+            candidate.payloadSchemaId.trim().length === 0 ||
+            candidate.payloadSchemaId.length > 128) {
+            throw new common_1.BadRequestException('payloadSchemaId must be a non-empty string.');
+        }
+        if (typeof candidate.payloadSchemaVersion !== 'number' ||
+            !Number.isInteger(candidate.payloadSchemaVersion) ||
+            candidate.payloadSchemaVersion < 1 ||
+            candidate.payloadSchemaVersion > 2_147_483_647) {
+            throw new common_1.BadRequestException('payloadSchemaVersion must be a positive signed 32-bit integer.');
+        }
+    }
+    notFound() {
+        throw new common_1.NotFoundException('Omni resource was not found in this scope.');
+    }
+    scopedWhere(where) {
+        if (typeof where === 'string') {
+            throw new common_1.BadRequestException('String where clauses are not supported for scoped Omni resources.');
+        }
+        if (Array.isArray(where)) {
+            return where.map((condition) => this.scopedConditions(condition));
+        }
+        return this.scopedConditions(where);
+    }
+    rejectScopeInWhere(where) {
+        if (!where || typeof where !== 'object')
+            return;
+        if (Array.isArray(where)) {
+            where.forEach((item) => this.rejectScopeInWhere(item));
+            return;
+        }
+        const candidate = where;
+        if (hasOwn(candidate, 'scopeId'))
+            this.rejectClientScope(candidate);
+        if (candidate.filters && typeof candidate.filters === 'object') {
+            this.rejectScopeInWhere(candidate.filters);
+        }
+        if (Array.isArray(candidate.childExpressions)) {
+            candidate.childExpressions.forEach((item) => this.rejectScopeInWhere(item));
+        }
+    }
+}
+exports.OmniScopedService = OmniScopedService;
+function isOmniScope(value) {
+    return (!!value &&
+        typeof value === 'object' &&
+        typeof value.scopeId === 'string' &&
+        typeof value.cacheKey === 'function');
+}
+const defaultOmniScope = {
+    scopeId: 'default',
+    cacheKey: (key) => `default:${key}`,
+};
+//# sourceMappingURL=omni-scoped.service.js.map

package/src/omni-scoped.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"omni-scoped.service.js","sourceRoot":"","sources":["omni-scoped.service.ts"],"names":[],"mappings":"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"}

package/src/omni-scoped.service.ts

@@ -0,0 +1,338 @@
+import { BadRequestException, NotFoundException } from '@nestjs/common';
+import type { CrudGenFindManyOptions } from '@nest-yalc-2/crud-gen/api-graphql/crud-gen-gql.interface.js';
+import type { IWhereCondition } from '@nest-yalc-2/crud-gen/api-graphql/crud-gen-gql.type.js';
+import { Operators } from '@nest-yalc-2/crud-gen/crud-gen.enum.js';
+import { GenericService } from '@nest-yalc-2/crud-gen/typeorm/generic.service.js';
+import type { DeepPartial, FindOptionsWhere, ObjectLiteral } from 'typeorm';
+import { IsNull } from 'typeorm';
+import type { OmniDeletePolicy, OmniScope } from './omni-scope.js';
+
+type ScopedEntity = ObjectLiteral & {
+  scopeId: string;
+  deletedAt?: Date | null;
+};
+
+function hasOwn(input: object, key: string): boolean {
+  return Object.prototype.hasOwnProperty.call(input, key);
+}
+
+/**
+ * The shared service boundary for scoped Omni CRUD. Every lookup, mutation,
+ * and generated grid is scoped before it reaches the generic CrudGen service.
+ */
+export class OmniScopedService<
+  Entity extends ScopedEntity,
+> extends GenericService<Entity> {
+  constructor(
+    repository: any,
+    scopeOrRepositoryWrite?: OmniScope | any,
+    private readonly deletion: OmniDeletePolicy = 'hard',
+  ) {
+    const scope = isOmniScope(scopeOrRepositoryWrite)
+      ? scopeOrRepositoryWrite
+      : defaultOmniScope;
+    super(
+      repository,
+      isOmniScope(scopeOrRepositoryWrite) ? undefined : scopeOrRepositoryWrite,
+    );
+    this.scope = scope;
+  }
+
+  protected readonly scope: OmniScope;
+
+  protected get scopeId(): string {
+    return this.scope.scopeId;
+  }
+
+  protected scopedConditions(
+    conditions: FindOptionsWhere<Entity>,
+  ): FindOptionsWhere<Entity> {
+    this.rejectClientScope(conditions as object);
+    return {
+      ...conditions,
+      scopeId: this.scopeId,
+      ...(this.deletion === 'tombstone' ? { deletedAt: IsNull() } : {}),
+    } as unknown as FindOptionsWhere<Entity>;
+  }
+
+  override async getEntity(
+    conditions:
+      | FindOptionsWhere<Entity>[]
+      | FindOptionsWhere<Entity>
+      | ObjectLiteral
+      | string,
+    fields?: (keyof Entity)[],
+    relations?: string[],
+    databaseName?: string,
+    options?: { failOnNull: false },
+  ): Promise<Entity | undefined>;
+  override async getEntity(
+    conditions:
+      | FindOptionsWhere<Entity>[]
+      | FindOptionsWhere<Entity>
+      | ObjectLiteral
+      | string,
+    fields?: (keyof Entity)[],
+    relations?: string[],
+    databaseName?: string,
+    options?: { failOnNull?: boolean },
+  ): Promise<Entity>;
+  override async getEntity(
+    conditions:
+      | FindOptionsWhere<Entity>[]
+      | FindOptionsWhere<Entity>
+      | ObjectLiteral
+      | string,
+    fields?: (keyof Entity)[],
+    relations?: string[],
+    databaseName?: string,
+    options?: { failOnNull?: boolean },
+  ): Promise<Entity | undefined> {
+    const entity = await super.getEntity(
+      this.scopedWhere(conditions),
+      fields,
+      relations,
+      databaseName,
+      { failOnNull: false },
+    );
+    if (!entity && options?.failOnNull) this.notFound();
+    return entity;
+  }
+
+  override async getEntityListExtended(
+    findOptions: CrudGenFindManyOptions<Entity>,
+    withCount?: false,
+    relations?: string[],
+    databaseName?: string,
+  ): Promise<Entity[]>;
+  override async getEntityListExtended(
+    findOptions: CrudGenFindManyOptions<Entity>,
+    withCount: true,
+    relations?: string[],
+    databaseName?: string,
+  ): Promise<[Entity[], number]>;
+  override async getEntityListExtended(
+    findOptions: CrudGenFindManyOptions<Entity> = {},
+    withCount = false,
+    relations?: string[],
+    databaseName?: string,
+  ): Promise<Entity[] | [Entity[], number]> {
+    const scopedOptions = this.scopeFindOptions(findOptions);
+    if (withCount) {
+      return super.getEntityListExtended(
+        scopedOptions,
+        true,
+        relations,
+        databaseName,
+      );
+    }
+    return super.getEntityListExtended(
+      scopedOptions,
+      false,
+      relations,
+      databaseName,
+    );
+  }
+
+  private scopeFindOptions(
+    findOptions: CrudGenFindManyOptions<Entity>,
+  ): CrudGenFindManyOptions<Entity> {
+    this.rejectScopeInWhere(findOptions.where);
+    const userWhere = findOptions.where;
+    const filters: IWhereCondition<Entity>['filters'] = {};
+    filters.scopeId = this.scopeId;
+    if (this.deletion === 'tombstone') filters.deletedAt = IsNull();
+    const where: IWhereCondition<Entity> = {
+      operator: Operators.AND,
+      filters,
+      ...(userWhere ? { childExpressions: [userWhere] } : {}),
+    };
+    return {
+      ...findOptions,
+      where,
+      ...(findOptions.subQueryFilters
+        ? {
+            subQueryFilters: this.scopeFindOptions(findOptions.subQueryFilters),
+          }
+        : {}),
+    };
+  }
+
+  override async createEntity(
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity?: true,
+  ): Promise<Entity>;
+  override async createEntity(
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity?: boolean,
+  ): Promise<Entity | boolean>;
+  override async createEntity(
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity = true,
+  ): Promise<Entity | boolean> {
+    this.rejectServerFields(input as object);
+    this.validatePayloadContract(input as object);
+    return super.createEntity(
+      { ...input, scopeId: this.scopeId } as DeepPartial<Entity>,
+      findOptions,
+      returnEntity,
+    );
+  }
+
+  override async updateEntity(
+    conditions: FindOptionsWhere<Entity>,
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity?: true,
+  ): Promise<Entity>;
+  override async updateEntity(
+    conditions: FindOptionsWhere<Entity>,
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity?: boolean,
+  ): Promise<Entity | boolean>;
+  override async updateEntity(
+    conditions: FindOptionsWhere<Entity>,
+    input: DeepPartial<Entity>,
+    findOptions?: CrudGenFindManyOptions<Entity>,
+    returnEntity = true,
+  ): Promise<Entity | boolean> {
+    this.rejectServerFields(input as object);
+    this.validatePayloadContract(input as object);
+    if (hasOwn(input as object, 'guid')) {
+      throw new BadRequestException('guid is immutable.');
+    }
+    return super.updateEntity(
+      this.scopedConditions(conditions),
+      { ...input, scopeId: this.scopeId } as DeepPartial<Entity>,
+      findOptions,
+      returnEntity,
+    );
+  }
+
+  override async deleteEntity(
+    conditions: FindOptionsWhere<Entity>,
+  ): Promise<boolean> {
+    const scoped = this.scopedConditions(conditions);
+    if (this.deletion === 'hard') {
+      return super.deleteEntity(scoped);
+    }
+    const result = await this.getRepository().update(scoped, {
+      deletedAt: new Date(),
+    } as DeepPartial<Entity>);
+    if (!result.affected) this.notFound();
+    return true;
+  }
+
+  protected rejectServerFields(input: object): void {
+    for (const field of ['scopeId', 'revision', 'deletedAt']) {
+      if (hasOwn(input, field)) {
+        throw new BadRequestException(`${field} is server-owned.`);
+      }
+    }
+  }
+
+  protected rejectClientScope(input: object): void {
+    if (hasOwn(input, 'scopeId')) {
+      throw new BadRequestException('scopeId is derived from server context.');
+    }
+  }
+
+  private validatePayloadContract(input: object): void {
+    const candidate = input as Record<string, unknown>;
+    if (
+      hasOwn(candidate, 'payload') &&
+      candidate.payload !== null &&
+      (typeof candidate.payload !== 'object' ||
+        Array.isArray(candidate.payload))
+    ) {
+      throw new BadRequestException('payload must be a JSON object or null.');
+    }
+
+    const hasSchemaId = hasOwn(candidate, 'payloadSchemaId');
+    const hasSchemaVersion = hasOwn(candidate, 'payloadSchemaVersion');
+    if (hasSchemaId !== hasSchemaVersion) {
+      throw new BadRequestException(
+        'payloadSchemaId and payloadSchemaVersion must be supplied together.',
+      );
+    }
+    if (!hasSchemaId) return;
+
+    if (
+      typeof candidate.payloadSchemaId !== 'string' ||
+      candidate.payloadSchemaId.trim().length === 0 ||
+      candidate.payloadSchemaId.length > 128
+    ) {
+      throw new BadRequestException(
+        'payloadSchemaId must be a non-empty string.',
+      );
+    }
+    if (
+      typeof candidate.payloadSchemaVersion !== 'number' ||
+      !Number.isInteger(candidate.payloadSchemaVersion) ||
+      candidate.payloadSchemaVersion < 1 ||
+      candidate.payloadSchemaVersion > 2_147_483_647
+    ) {
+      throw new BadRequestException(
+        'payloadSchemaVersion must be a positive signed 32-bit integer.',
+      );
+    }
+  }
+
+  protected notFound(): never {
+    throw new NotFoundException('Omni resource was not found in this scope.');
+  }
+
+  private scopedWhere(
+    where:
+      | FindOptionsWhere<Entity>[]
+      | FindOptionsWhere<Entity>
+      | ObjectLiteral
+      | string,
+  ): FindOptionsWhere<Entity> | FindOptionsWhere<Entity>[] {
+    if (typeof where === 'string') {
+      throw new BadRequestException(
+        'String where clauses are not supported for scoped Omni resources.',
+      );
+    }
+    if (Array.isArray(where)) {
+      return where.map((condition) => this.scopedConditions(condition));
+    }
+    return this.scopedConditions(where as FindOptionsWhere<Entity>);
+  }
+
+  private rejectScopeInWhere(where: unknown): void {
+    if (!where || typeof where !== 'object') return;
+    if (Array.isArray(where)) {
+      where.forEach((item) => this.rejectScopeInWhere(item));
+      return;
+    }
+    const candidate = where as Record<string, unknown>;
+    if (hasOwn(candidate, 'scopeId')) this.rejectClientScope(candidate);
+    if (candidate.filters && typeof candidate.filters === 'object') {
+      this.rejectScopeInWhere(candidate.filters);
+    }
+    if (Array.isArray(candidate.childExpressions)) {
+      candidate.childExpressions.forEach((item) =>
+        this.rejectScopeInWhere(item),
+      );
+    }
+  }
+}
+
+function isOmniScope(value: unknown): value is OmniScope {
+  return (
+    !!value &&
+    typeof value === 'object' &&
+    typeof (value as OmniScope).scopeId === 'string' &&
+    typeof (value as OmniScope).cacheKey === 'function'
+  );
+}
+
+const defaultOmniScope: OmniScope = {
+  scopeId: 'default',
+  cacheKey: (key) => `default:${key}`,
+};

package/src/omnikernel.diagnostics.d.ts

@@ -0,0 +1,16 @@
+import type { DataSource } from 'typeorm';
+export interface OmniKernelQueryPlanEvidence {
+    dialect: 'sqlite' | 'postgres';
+    recordGridPlan: readonly string[];
+    relationSourcePlan: readonly string[];
+    usesRecordGridIndex: boolean;
+    usesRelationSourceIndex: boolean;
+}
+export declare function collectOmniKernelQueryPlanEvidence(dataSource: DataSource, sample: {
+    scopeId: string;
+    recordKind: string;
+    recordStatus: string;
+    sourceRecordId: string;
+    relationKind: string;
+    relationStatus: string;
+}): Promise<OmniKernelQueryPlanEvidence>;

package/src/omnikernel.diagnostics.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectOmniKernelQueryPlanEvidence = collectOmniKernelQueryPlanEvidence;
+const recordGridIndex = 'omni_record_scope_kind_status_guid_idx';
+const relationSourceIndex = 'omni_relation_scope_source_kind_status_created_guid_idx';
+async function collectOmniKernelQueryPlanEvidence(dataSource, sample) {
+    const dialect = dataSource.options.type;
+    if (dialect !== 'sqlite' && dialect !== 'postgres') {
+        throw new TypeError('OmniKernel diagnostics support sqlite and postgres only.');
+    }
+    const statements = dialect === 'sqlite'
+        ? {
+            record: `EXPLAIN QUERY PLAN SELECT "guid" FROM "omni-record" WHERE "scopeId" = ? AND "kind" = ? AND "status" = ? AND "deletedAt" IS NULL ORDER BY "guid"`,
+            relation: `EXPLAIN QUERY PLAN SELECT "guid" FROM "omni-relation" WHERE "scopeId" = ? AND "sourceRecordId" = ? AND "kind" = ? AND "status" = ? ORDER BY "createdAt", "guid"`,
+        }
+        : {
+            record: `EXPLAIN (FORMAT JSON) SELECT "guid" FROM "omni-record" WHERE "scopeId" = $1 AND "kind" = $2 AND "status" = $3 AND "deletedAt" IS NULL ORDER BY "guid"`,
+            relation: `EXPLAIN (FORMAT JSON) SELECT "guid" FROM "omni-relation" WHERE "scopeId" = $1 AND "sourceRecordId" = $2 AND "kind" = $3 AND "status" = $4 ORDER BY "createdAt", "guid"`,
+        };
+    const recordResult = await dataSource.query(statements.record, [
+        sample.scopeId,
+        sample.recordKind,
+        sample.recordStatus,
+    ]);
+    const relationResult = await dataSource.query(statements.relation, [
+        sample.scopeId,
+        sample.sourceRecordId,
+        sample.relationKind,
+        sample.relationStatus,
+    ]);
+    const recordGridPlan = flattenPlan(recordResult);
+    const relationSourcePlan = flattenPlan(relationResult);
+    return {
+        dialect,
+        recordGridPlan,
+        relationSourcePlan,
+        usesRecordGridIndex: containsIndex(recordGridPlan, recordGridIndex),
+        usesRelationSourceIndex: containsIndex(relationSourcePlan, relationSourceIndex),
+    };
+}
+function flattenPlan(result) {
+    return JSON.stringify(result)
+        .replaceAll('\\n', ' ')
+        .split(/(?<=\}),|\n/)
+        .filter((line) => line.length > 0);
+}
+function containsIndex(plan, indexName) {
+    return plan.some((line) => line.includes(indexName));
+}
+//# sourceMappingURL=omnikernel.diagnostics.js.map

package/src/omnikernel.diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"omnikernel.diagnostics.js","sourceRoot":"","sources":["omnikernel.diagnostics.ts"],"names":[],"mappings":";;AAkBA,gFAqDC;AA7DD,MAAM,eAAe,GAAG,wCAAwC,CAAC;AACjE,MAAM,mBAAmB,GACvB,yDAAyD,CAAC;AAMrD,KAAK,UAAU,kCAAkC,CACtD,UAAsB,EACtB,MAOC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,OAAO,CAAC,IAAI,CAAC;IACxC,IAAI,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QACnD,MAAM,IAAI,SAAS,CACjB,0DAA0D,CAC3D,CAAC;IACJ,CAAC;IAED,MAAM,UAAU,GACd,OAAO,KAAK,QAAQ;QAClB,CAAC,CAAC;YACE,MAAM,EAAE,iJAAiJ;YACzJ,QAAQ,EAAE,iKAAiK;SAC5K;QACH,CAAC,CAAC;YACE,MAAM,EAAE,uJAAuJ;YAC/J,QAAQ,EAAE,wKAAwK;SACnL,CAAC;IAER,MAAM,YAAY,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,MAAM,EAAE;QAC7D,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,UAAU;QACjB,MAAM,CAAC,YAAY;KACpB,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,MAAM,UAAU,CAAC,KAAK,CAAC,UAAU,CAAC,QAAQ,EAAE;QACjE,MAAM,CAAC,OAAO;QACd,MAAM,CAAC,cAAc;QACrB,MAAM,CAAC,YAAY;QACnB,MAAM,CAAC,cAAc;KACtB,CAAC,CAAC;IACH,MAAM,cAAc,GAAG,WAAW,CAAC,YAAY,CAAC,CAAC;IACjD,MAAM,kBAAkB,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IAEvD,OAAO;QACL,OAAO;QACP,cAAc;QACd,kBAAkB;QAClB,mBAAmB,EAAE,aAAa,CAAC,cAAc,EAAE,eAAe,CAAC;QACnE,uBAAuB,EAAE,aAAa,CACpC,kBAAkB,EAClB,mBAAmB,CACpB;KACF,CAAC;AACJ,CAAC;AAED,SAAS,WAAW,CAAC,MAAe;IAClC,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC;SAC1B,UAAU,CAAC,KAAK,EAAE,GAAG,CAAC;SACtB,KAAK,CAAC,aAAa,CAAC;SACpB,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACvC,CAAC;AAED,SAAS,aAAa,CAAC,IAAuB,EAAE,SAAiB;IAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AACvD,CAAC"}