@nest-yalc-2/omnikernel-module 2.2.2 → 2.2.6

package/src/omni-relation.service.ts

@@ -1,159 +1,159 @@
-import { BadRequestException } from '@nestjs/common';
-import type { CrudGenFindManyOptions } from '@nest-yalc-2/crud-gen/api-graphql/crud-gen-gql.interface.js';
-import {
-  IsNull,
-  type DeepPartial,
-  type FindOptionsWhere,
-  type Repository,
-} from 'typeorm';
-import { OmniRecordEntity } from './base/omni-record.entity.js';
-import { OmniRelationEntity } from './base/omni-relation.entity.js';
-import {
-  canonicalOmniRelationKinds,
-  type OmniRelationKindContract,
-} from './omni-relation-kind.contract.js';
-import { isAllowedOmniRelation } from './omni-relation-semantics.js';
-import type { OmniDeletePolicy, OmniScope } from './omni-scope.js';
-import { OmniScopedService } from './omni-scoped.service.js';
-
-/**
- * Scoped graph CRUD with immutable endpoints. The database composite foreign
- * keys prevent cross-scope edges; this service additionally turns missing or
- * invalid endpoints into normal API failures before persistence.
- */
-export class OmniRelationService extends OmniScopedService<OmniRelationEntity> {
-  constructor(
-    repository: any,
-    scope: OmniScope,
-    deletion: OmniDeletePolicy,
-    protected readonly recordRepository: Repository<OmniRecordEntity>,
-    protected readonly kinds: OmniRelationKindContract,
-  ) {
-    super(repository, scope, deletion);
-  }
-
-  override async createEntity(
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity?: true,
-  ): Promise<OmniRelationEntity>;
-  override async createEntity(
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity?: boolean,
-  ): Promise<OmniRelationEntity | boolean>;
-  override async createEntity(
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity = true,
-  ): Promise<OmniRelationEntity | boolean> {
-    this.rejectServerFields(input as object);
-    await this.assertRelation(input);
-    return super.createEntity(input, findOptions, returnEntity);
-  }
-
-  override async updateEntity(
-    conditions: FindOptionsWhere<OmniRelationEntity>,
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity?: true,
-  ): Promise<OmniRelationEntity>;
-  override async updateEntity(
-    conditions: FindOptionsWhere<OmniRelationEntity>,
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity?: boolean,
-  ): Promise<OmniRelationEntity | boolean>;
-  override async updateEntity(
-    conditions: FindOptionsWhere<OmniRelationEntity>,
-    input: DeepPartial<OmniRelationEntity>,
-    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
-    returnEntity = true,
-  ): Promise<OmniRelationEntity | boolean> {
-    for (const field of ['guid', 'sourceRecordId', 'targetRecordId']) {
-      if (Object.prototype.hasOwnProperty.call(input, field)) {
-        throw new BadRequestException(`Omni relation ${field} is immutable.`);
-      }
-    }
-
-    const current = await super.getEntity(
-      conditions,
-      undefined,
-      undefined,
-      undefined,
-      {
-        failOnNull: true,
-      },
-    );
-    if (!current) this.notFound();
-    await this.assertRelation({ ...current, ...input });
-    return super.updateEntity(conditions, input, findOptions, returnEntity);
-  }
-
-  protected async assertRelation(
-    input: DeepPartial<OmniRelationEntity>,
-    recordRepository: Repository<OmniRecordEntity> = this.recordRepository,
-  ): Promise<void> {
-    const sourceRecordId = this.requiredIdentifier(
-      input.sourceRecordId,
-      'sourceRecordId',
-    );
-    const targetRecordId = this.requiredIdentifier(
-      input.targetRecordId,
-      'targetRecordId',
-    );
-    const kind = this.requiredIdentifier(input.kind, 'kind');
-    try {
-      this.kinds.assert(kind);
-    } catch (error) {
-      throw new BadRequestException(
-        error instanceof Error
-          ? error.message
-          : 'Omni relation kind is invalid.',
-      );
-    }
-
-    const records = await recordRepository.find({
-      where: [
-        { scopeId: this.scopeId, guid: sourceRecordId, deletedAt: IsNull() },
-        { scopeId: this.scopeId, guid: targetRecordId, deletedAt: IsNull() },
-      ],
-    });
-    const source = records.find((record) => record.guid === sourceRecordId);
-    const target = records.find((record) => record.guid === targetRecordId);
-    if (!source || !target) this.notFound();
-
-    this.assertEndpointKinds(source, target);
-
-    const isCanonical = canonicalOmniRelationKinds.includes(
-      kind as (typeof canonicalOmniRelationKinds)[number],
-    );
-    if (
-      isCanonical &&
-      !isAllowedOmniRelation({
-        sourceKind: source.kind,
-        targetKind: target.kind,
-        relationKind: kind,
-      })
-    ) {
-      throw new BadRequestException(
-        'Omni relation kind is not valid for these endpoint kinds.',
-      );
-    }
-  }
-
-  /** Resource-specific relation projections may narrow endpoint kinds. */
-  protected assertEndpointKinds(
-    _source: OmniRecordEntity,
-    _target: OmniRecordEntity,
-  ): void {}
-
-  protected requiredIdentifier(value: unknown, field: string): string {
-    if (typeof value !== 'string' || value.trim().length === 0) {
-      throw new BadRequestException(
-        `Omni relation ${field} must be a non-empty string.`,
-      );
-    }
-    return value;
-  }
-}
+import { BadRequestException } from '@nestjs/common';
+import type { CrudGenFindManyOptions } from '@nest-yalc-2/crud-gen/api-graphql/crud-gen-gql.interface.js';
+import {
+  IsNull,
+  type DeepPartial,
+  type FindOptionsWhere,
+  type Repository,
+} from 'typeorm';
+import { OmniRecordEntity } from './base/omni-record.entity.js';
+import { OmniRelationEntity } from './base/omni-relation.entity.js';
+import {
+  canonicalOmniRelationKinds,
+  type OmniRelationKindContract,
+} from './omni-relation-kind.contract.js';
+import { isAllowedOmniRelation } from './omni-relation-semantics.js';
+import type { OmniDeletePolicy, OmniScope } from './omni-scope.js';
+import { OmniScopedService } from './omni-scoped.service.js';
+
+/**
+ * Scoped graph CRUD with immutable endpoints. The database composite foreign
+ * keys prevent cross-scope edges; this service additionally turns missing or
+ * invalid endpoints into normal API failures before persistence.
+ */
+export class OmniRelationService extends OmniScopedService<OmniRelationEntity> {
+  constructor(
+    repository: any,
+    scope: OmniScope,
+    deletion: OmniDeletePolicy,
+    protected readonly recordRepository: Repository<OmniRecordEntity>,
+    protected readonly kinds: OmniRelationKindContract,
+  ) {
+    super(repository, scope, deletion);
+  }
+
+  override async createEntity(
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity?: true,
+  ): Promise<OmniRelationEntity>;
+  override async createEntity(
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity?: boolean,
+  ): Promise<OmniRelationEntity | boolean>;
+  override async createEntity(
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity = true,
+  ): Promise<OmniRelationEntity | boolean> {
+    this.rejectServerFields(input as object);
+    await this.assertRelation(input);
+    return super.createEntity(input, findOptions, returnEntity);
+  }
+
+  override async updateEntity(
+    conditions: FindOptionsWhere<OmniRelationEntity>,
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity?: true,
+  ): Promise<OmniRelationEntity>;
+  override async updateEntity(
+    conditions: FindOptionsWhere<OmniRelationEntity>,
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity?: boolean,
+  ): Promise<OmniRelationEntity | boolean>;
+  override async updateEntity(
+    conditions: FindOptionsWhere<OmniRelationEntity>,
+    input: DeepPartial<OmniRelationEntity>,
+    findOptions?: CrudGenFindManyOptions<OmniRelationEntity>,
+    returnEntity = true,
+  ): Promise<OmniRelationEntity | boolean> {
+    for (const field of ['guid', 'sourceRecordId', 'targetRecordId']) {
+      if (Object.prototype.hasOwnProperty.call(input, field)) {
+        throw new BadRequestException(`Omni relation ${field} is immutable.`);
+      }
+    }
+
+    const current = await super.getEntity(
+      conditions,
+      undefined,
+      undefined,
+      undefined,
+      {
+        failOnNull: true,
+      },
+    );
+    if (!current) this.notFound();
+    await this.assertRelation({ ...current, ...input });
+    return super.updateEntity(conditions, input, findOptions, returnEntity);
+  }
+
+  protected async assertRelation(
+    input: DeepPartial<OmniRelationEntity>,
+    recordRepository: Repository<OmniRecordEntity> = this.recordRepository,
+  ): Promise<void> {
+    const sourceRecordId = this.requiredIdentifier(
+      input.sourceRecordId,
+      'sourceRecordId',
+    );
+    const targetRecordId = this.requiredIdentifier(
+      input.targetRecordId,
+      'targetRecordId',
+    );
+    const kind = this.requiredIdentifier(input.kind, 'kind');
+    try {
+      this.kinds.assert(kind);
+    } catch (error) {
+      throw new BadRequestException(
+        error instanceof Error
+          ? error.message
+          : 'Omni relation kind is invalid.',
+      );
+    }
+
+    const records = await recordRepository.find({
+      where: [
+        { scopeId: this.scopeId, guid: sourceRecordId, deletedAt: IsNull() },
+        { scopeId: this.scopeId, guid: targetRecordId, deletedAt: IsNull() },
+      ],
+    });
+    const source = records.find((record) => record.guid === sourceRecordId);
+    const target = records.find((record) => record.guid === targetRecordId);
+    if (!source || !target) this.notFound();
+
+    this.assertEndpointKinds(source, target);
+
+    const isCanonical = canonicalOmniRelationKinds.includes(
+      kind as (typeof canonicalOmniRelationKinds)[number],
+    );
+    if (
+      isCanonical &&
+      !isAllowedOmniRelation({
+        sourceKind: source.kind,
+        targetKind: target.kind,
+        relationKind: kind,
+      })
+    ) {
+      throw new BadRequestException(
+        'Omni relation kind is not valid for these endpoint kinds.',
+      );
+    }
+  }
+
+  /** Resource-specific relation projections may narrow endpoint kinds. */
+  protected assertEndpointKinds(
+    _source: OmniRecordEntity,
+    _target: OmniRecordEntity,
+  ): void {}
+
+  protected requiredIdentifier(value: unknown, field: string): string {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      throw new BadRequestException(
+        `Omni relation ${field} must be a non-empty string.`,
+      );
+    }
+    return value;
+  }
+}

package/src/omni-scope.ts

@@ -1,161 +1,161 @@
-import { Inject, Injectable, Scope } from '@nestjs/common';
-import { REQUEST } from '@nestjs/core';
-
-export interface OmniScope {
-  readonly scopeId: string;
-  cacheKey(key: string): string;
-}
-
-export type OmniScopeResolver = (request: unknown) => string | undefined;
-
-export interface OmniKernelRegistrationOptions {
-  dbConnection: string;
-  /**
-   * Authentication adapters resolve a trusted server scope from the request.
-   * The adapter owns authentication; OmniKernel never reads a client DTO field.
-   */
-  resolveScope?: OmniScopeResolver;
-  /**
-   * Compatibility/default partition for applications that do not yet have an
-   * authentication adapter. It is server configuration, never request input.
-   */
-  defaultScopeId?: string;
-  /** Kinds exclusively owned by registered extension projections. */
-  reservedRecordKinds?: readonly string[];
-  relationKinds?: readonly string[];
-  deletion?: Partial<OmniDeletionPolicies>;
-}
-
-export type OmniDeletePolicy = 'hard' | 'tombstone';
-
-export interface OmniDeletionPolicies {
-  named: OmniDeletePolicy;
-  record: OmniDeletePolicy;
-  document: OmniDeletePolicy;
-  collection: OmniDeletePolicy;
-  relation: OmniDeletePolicy;
-  externalRef: OmniDeletePolicy;
-}
-
-export const OMNI_KERNEL_OPTIONS = Symbol('OMNI_KERNEL_OPTIONS');
-
-export const defaultOmniDeletionPolicies: OmniDeletionPolicies = {
-  named: 'hard',
-  record: 'tombstone',
-  document: 'tombstone',
-  collection: 'tombstone',
-  relation: 'hard',
-  externalRef: 'hard',
-};
-
-function normalizeOmniDeletionPolicies(
-  deletion: Partial<OmniDeletionPolicies> | undefined,
-): OmniDeletionPolicies {
-  const knownResources = new Set(Object.keys(defaultOmniDeletionPolicies));
-  for (const [resource, policy] of Object.entries(deletion ?? {})) {
-    if (!knownResources.has(resource)) {
-      throw new TypeError(
-        `Unknown OmniKernel deletion policy resource: ${resource}.`,
-      );
-    }
-    if (policy !== 'hard' && policy !== 'tombstone') {
-      throw new TypeError(
-        `OmniKernel deletion policy for ${resource} must be hard or tombstone.`,
-      );
-    }
-  }
-  return {
-    ...defaultOmniDeletionPolicies,
-    ...deletion,
-  };
-}
-
-export function normalizeOmniKernelRegistrationOptions(
-  options: string | OmniKernelRegistrationOptions,
-): Required<
-  Pick<
-    OmniKernelRegistrationOptions,
-    'dbConnection' | 'defaultScopeId' | 'relationKinds'
-  >
-> &
-  Omit<
-    OmniKernelRegistrationOptions,
-    | 'dbConnection'
-    | 'defaultScopeId'
-    | 'relationKinds'
-    | 'reservedRecordKinds'
-    | 'deletion'
-  > & {
-    reservedRecordKinds: readonly string[];
-    deletion: OmniDeletionPolicies;
-  } {
-  const candidate =
-    typeof options === 'string' ? { dbConnection: options } : options;
-  if (!candidate.dbConnection) {
-    throw new TypeError(
-      'OmniKernelModule requires a database connection name.',
-    );
-  }
-  if (
-    candidate.defaultScopeId !== undefined &&
-    (candidate.defaultScopeId.trim().length === 0 ||
-      candidate.defaultScopeId.length > 64)
-  ) {
-    throw new TypeError('OmniKernel defaultScopeId must be 1-64 characters.');
-  }
-  const reservedRecordKinds = candidate.reservedRecordKinds ?? [];
-  if (
-    !Array.isArray(reservedRecordKinds) ||
-    reservedRecordKinds.some(
-      (kind) =>
-        typeof kind !== 'string' ||
-        kind.trim().length === 0 ||
-        kind.length > 64,
-    ) ||
-    new Set(reservedRecordKinds).size !== reservedRecordKinds.length
-  ) {
-    throw new TypeError(
-      'OmniKernel reservedRecordKinds must be unique 1-64 character strings.',
-    );
-  }
-
-  return {
-    ...candidate,
-    defaultScopeId: candidate.defaultScopeId ?? 'default',
-    relationKinds: candidate.relationKinds ?? [],
-    reservedRecordKinds: Object.freeze([...reservedRecordKinds]),
-    deletion: normalizeOmniDeletionPolicies(candidate.deletion),
-  };
-}
-
-type RequestEnvelope = { req?: unknown };
-
-/**
- * Request-scoped server context used by every Omni generated API and loader.
- * It is intentionally unavailable when neither the trusted adapter nor a
- * configured default provides a scope.
- */
-@Injectable({ scope: Scope.REQUEST })
-export class OmniScopeContext implements OmniScope {
-  readonly scopeId: string;
-
-  constructor(
-    @Inject(REQUEST) request: unknown,
-    @Inject(OMNI_KERNEL_OPTIONS)
-    options: ReturnType<typeof normalizeOmniKernelRegistrationOptions>,
-  ) {
-    const requestForResolver =
-      (request as RequestEnvelope | undefined)?.req ?? request;
-    const scopeId = options.resolveScope
-      ? options.resolveScope(requestForResolver)
-      : options.defaultScopeId;
-    if (!scopeId || scopeId.trim().length === 0 || scopeId.length > 64) {
-      throw new TypeError('Omni scope context is unavailable.');
-    }
-    this.scopeId = scopeId;
-  }
-
-  cacheKey(key: string): string {
-    return `${this.scopeId}:${key}`;
-  }
-}
+import { Inject, Injectable, Scope } from '@nestjs/common';
+import { REQUEST } from '@nestjs/core';
+
+export interface OmniScope {
+  readonly scopeId: string;
+  cacheKey(key: string): string;
+}
+
+export type OmniScopeResolver = (request: unknown) => string | undefined;
+
+export interface OmniKernelRegistrationOptions {
+  dbConnection: string;
+  /**
+   * Authentication adapters resolve a trusted server scope from the request.
+   * The adapter owns authentication; OmniKernel never reads a client DTO field.
+   */
+  resolveScope?: OmniScopeResolver;
+  /**
+   * Compatibility/default partition for applications that do not yet have an
+   * authentication adapter. It is server configuration, never request input.
+   */
+  defaultScopeId?: string;
+  /** Kinds exclusively owned by registered extension projections. */
+  reservedRecordKinds?: readonly string[];
+  relationKinds?: readonly string[];
+  deletion?: Partial<OmniDeletionPolicies>;
+}
+
+export type OmniDeletePolicy = 'hard' | 'tombstone';
+
+export interface OmniDeletionPolicies {
+  named: OmniDeletePolicy;
+  record: OmniDeletePolicy;
+  document: OmniDeletePolicy;
+  collection: OmniDeletePolicy;
+  relation: OmniDeletePolicy;
+  externalRef: OmniDeletePolicy;
+}
+
+export const OMNI_KERNEL_OPTIONS = Symbol('OMNI_KERNEL_OPTIONS');
+
+export const defaultOmniDeletionPolicies: OmniDeletionPolicies = {
+  named: 'hard',
+  record: 'tombstone',
+  document: 'tombstone',
+  collection: 'tombstone',
+  relation: 'hard',
+  externalRef: 'hard',
+};
+
+function normalizeOmniDeletionPolicies(
+  deletion: Partial<OmniDeletionPolicies> | undefined,
+): OmniDeletionPolicies {
+  const knownResources = new Set(Object.keys(defaultOmniDeletionPolicies));
+  for (const [resource, policy] of Object.entries(deletion ?? {})) {
+    if (!knownResources.has(resource)) {
+      throw new TypeError(
+        `Unknown OmniKernel deletion policy resource: ${resource}.`,
+      );
+    }
+    if (policy !== 'hard' && policy !== 'tombstone') {
+      throw new TypeError(
+        `OmniKernel deletion policy for ${resource} must be hard or tombstone.`,
+      );
+    }
+  }
+  return {
+    ...defaultOmniDeletionPolicies,
+    ...deletion,
+  };
+}
+
+export function normalizeOmniKernelRegistrationOptions(
+  options: string | OmniKernelRegistrationOptions,
+): Required<
+  Pick<
+    OmniKernelRegistrationOptions,
+    'dbConnection' | 'defaultScopeId' | 'relationKinds'
+  >
+> &
+  Omit<
+    OmniKernelRegistrationOptions,
+    | 'dbConnection'
+    | 'defaultScopeId'
+    | 'relationKinds'
+    | 'reservedRecordKinds'
+    | 'deletion'
+  > & {
+    reservedRecordKinds: readonly string[];
+    deletion: OmniDeletionPolicies;
+  } {
+  const candidate =
+    typeof options === 'string' ? { dbConnection: options } : options;
+  if (!candidate.dbConnection) {
+    throw new TypeError(
+      'OmniKernelModule requires a database connection name.',
+    );
+  }
+  if (
+    candidate.defaultScopeId !== undefined &&
+    (candidate.defaultScopeId.trim().length === 0 ||
+      candidate.defaultScopeId.length > 64)
+  ) {
+    throw new TypeError('OmniKernel defaultScopeId must be 1-64 characters.');
+  }
+  const reservedRecordKinds = candidate.reservedRecordKinds ?? [];
+  if (
+    !Array.isArray(reservedRecordKinds) ||
+    reservedRecordKinds.some(
+      (kind) =>
+        typeof kind !== 'string' ||
+        kind.trim().length === 0 ||
+        kind.length > 64,
+    ) ||
+    new Set(reservedRecordKinds).size !== reservedRecordKinds.length
+  ) {
+    throw new TypeError(
+      'OmniKernel reservedRecordKinds must be unique 1-64 character strings.',
+    );
+  }
+
+  return {
+    ...candidate,
+    defaultScopeId: candidate.defaultScopeId ?? 'default',
+    relationKinds: candidate.relationKinds ?? [],
+    reservedRecordKinds: Object.freeze([...reservedRecordKinds]),
+    deletion: normalizeOmniDeletionPolicies(candidate.deletion),
+  };
+}
+
+type RequestEnvelope = { req?: unknown };
+
+/**
+ * Request-scoped server context used by every Omni generated API and loader.
+ * It is intentionally unavailable when neither the trusted adapter nor a
+ * configured default provides a scope.
+ */
+@Injectable({ scope: Scope.REQUEST })
+export class OmniScopeContext implements OmniScope {
+  readonly scopeId: string;
+
+  constructor(
+    @Inject(REQUEST) request: unknown,
+    @Inject(OMNI_KERNEL_OPTIONS)
+    options: ReturnType<typeof normalizeOmniKernelRegistrationOptions>,
+  ) {
+    const requestForResolver =
+      (request as RequestEnvelope | undefined)?.req ?? request;
+    const scopeId = options.resolveScope
+      ? options.resolveScope(requestForResolver)
+      : options.defaultScopeId;
+    if (!scopeId || scopeId.trim().length === 0 || scopeId.length > 64) {
+      throw new TypeError('Omni scope context is unavailable.');
+    }
+    this.scopeId = scopeId;
+  }
+
+  cacheKey(key: string): string {
+    return `${this.scopeId}:${key}`;
+  }
+}