nestjs-ddd-cli 3.2.2 → 3.3.0

package/dist/templates/recipes/external-projection-worker/canonical-json.ts.hbs

@@ -0,0 +1,123 @@
+import { createHash } from 'node:crypto';
+import type { ExternalProjectionJsonValue } from './external-projection-worker.types';
+
+export const EXTERNAL_PROJECTION_MAX_JSON_BYTES = 262_144;
+const MAX_DEPTH = 32;
+const MAX_NODES = 10_000;
+
+export interface CanonicalExternalProjectionJson {
+  value: ExternalProjectionJsonValue;
+  text: string;
+  sha256: string;
+}
+
+interface CanonicalizationState {
+  nodes: number;
+  stack: WeakSet<object>;
+}
+
+interface CanonicalNode {
+  value: ExternalProjectionJsonValue;
+  text: string;
+}
+
+function canonicalNumber(value: number): CanonicalNode {
+  if (!Number.isFinite(value)) {
+    throw new TypeError('External projection JSON requires finite numbers');
+  }
+  const normalized = Object.is(value, -0) ? 0 : value;
+  return { value: normalized, text: JSON.stringify(normalized) };
+}
+
+function canonicalArray(
+  value: unknown[],
+  depth: number,
+  state: CanonicalizationState,
+): CanonicalNode {
+  const children: CanonicalNode[] = [];
+  for (let index = 0; index < value.length; index += 1) {
+    if (!Object.hasOwn(value, index)) {
+      throw new TypeError('External projection JSON cannot contain sparse arrays');
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError('External projection JSON arrays require enumerable data elements');
+    }
+    children.push(canonicalNode(descriptor.value, depth + 1, state));
+  }
+  return {
+    value: children.map((child) => child.value),
+    text: `[${children.map((child) => child.text).join(',')}]`,
+  };
+}
+
+function canonicalObject(
+  value: object,
+  depth: number,
+  state: CanonicalizationState,
+): CanonicalNode {
+  const prototype = Object.getPrototypeOf(value) as object | null;
+  if (prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError('External projection JSON requires plain objects');
+  }
+  const properties = Reflect.ownKeys(value);
+  if (properties.some((key) => typeof key !== 'string')) {
+    throw new TypeError('External projection JSON cannot contain symbol keys');
+  }
+  const keys = (properties as string[]).sort((left, right) => {
+    if (left < right) return -1;
+    if (left > right) return 1;
+    return 0;
+  });
+  const output = Object.create(null) as Record<string, ExternalProjectionJsonValue>;
+  const entries: string[] = [];
+  for (const key of keys) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (!descriptor?.enumerable || !('value' in descriptor)) {
+      throw new TypeError('External projection JSON requires enumerable data properties');
+    }
+    const child = canonicalNode(descriptor.value, depth + 1, state);
+    output[key] = child.value;
+    entries.push(`${JSON.stringify(key)}:${child.text}`);
+  }
+  return { value: output, text: `{${entries.join(',')}}` };
+}
+
+function canonicalNode(value: unknown, depth: number, state: CanonicalizationState): CanonicalNode {
+  if (depth > MAX_DEPTH || ++state.nodes > MAX_NODES) {
+    throw new Error('External projection JSON exceeds structural limits');
+  }
+  if (value === null) return { value: null, text: 'null' };
+  if (typeof value === 'boolean') return { value, text: value ? 'true' : 'false' };
+  if (typeof value === 'string') return { value, text: JSON.stringify(value) };
+  if (typeof value === 'number') return canonicalNumber(value);
+  if (typeof value !== 'object') {
+    throw new TypeError('External projection payload must contain only JSON values');
+  }
+  if (state.stack.has(value)) throw new Error('External projection JSON cannot contain cycles');
+  state.stack.add(value);
+  try {
+    return Array.isArray(value)
+      ? canonicalArray(value, depth, state)
+      : canonicalObject(value, depth, state);
+  } finally {
+    state.stack.delete(value);
+  }
+}
+
+export function canonicalizeExternalProjectionJson(
+  value: unknown,
+  maxBytes = EXTERNAL_PROJECTION_MAX_JSON_BYTES,
+): CanonicalExternalProjectionJson {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > 1_048_576) {
+    throw new Error('External projection JSON byte limit is invalid');
+  }
+  const canonical = canonicalNode(value, 0, { nodes: 0, stack: new WeakSet<object>() });
+  if (Buffer.byteLength(canonical.text, 'utf8') > maxBytes) {
+    throw new Error('External projection JSON exceeds its byte limit');
+  }
+  return {
+    ...canonical,
+    sha256: createHash('sha256').update(canonical.text).digest('hex'),
+  };
+}

package/dist/templates/recipes/external-projection-worker/enqueuer.ts.hbs

@@ -0,0 +1,167 @@
+import { randomUUID } from 'node:crypto';
+import { Injectable } from '@nestjs/common';
+import type { EntityManager } from 'typeorm';
+import { canonicalizeExternalProjectionJson } from './canonical-json';
+import {
+  EnqueuedExternalProjection,
+  ExternalProjectionIdempotencyConflictError,
+  ExternalProjectionIntent,
+  ExternalProjectionOperation,
+  ExternalProjectionStatus,
+} from './external-projection-worker.types';
+
+type DatabaseDate = Date | string | null;
+
+interface OperationRow {
+  id: string;
+  projection_name: string;
+  target_key: string;
+  operation_kind: string;
+  idempotency_key: string;
+  payload: unknown;
+  payload_hash: string;
+  status: ExternalProjectionStatus;
+  attempt_count: number | string;
+  result_reference: string | null;
+  next_attempt_at: DatabaseDate;
+  last_attempt_at: DatabaseDate;
+  applied_at: DatabaseDate;
+  last_error_code: string | null;
+  created_at: Date | string;
+  updated_at: Date | string;
+}
+
+function requiredIdentifier(value: string, name: string, maximum: number): string {
+  const normalized = value.trim();
+  if (
+    normalized.length < 1 ||
+    normalized.length > maximum ||
+    !/^[A-Za-z0-9][A-Za-z0-9._:-]*$/.test(normalized)
+  ) {
+    throw new Error(`External projection ${name} is invalid`);
+  }
+  return normalized;
+}
+
+function requiredTargetKey(value: string): string {
+  const normalized = value.trim();
+  if (
+    normalized.length < 1 ||
+    normalized.length > 500 ||
+    /[\u0000-\u001f\u007f]/.test(normalized)
+  ) {
+    throw new Error('External projection target key is invalid');
+  }
+  return normalized;
+}
+
+function rowsFromQuery<T>(result: unknown): T[] {
+  if (!Array.isArray(result)) return [];
+  return Array.isArray(result[0]) ? (result[0] as T[]) : (result as T[]);
+}
+
+function optionalDate(value: Date | string | null): Date | undefined {
+  return value === null ? undefined : new Date(value);
+}
+
+function operationFromRow(row: OperationRow): ExternalProjectionOperation {
+  const payload = canonicalizeExternalProjectionJson(row.payload).value;
+  return {
+    id: row.id,
+    projectionName: row.projection_name,
+    targetKey: row.target_key,
+    operationKind: row.operation_kind,
+    idempotencyKey: row.idempotency_key,
+    payload,
+    payloadHash: row.payload_hash,
+    status: row.status,
+    attemptCount: Number(row.attempt_count),
+    resultReference: row.result_reference ?? undefined,
+    nextAttemptAt: optionalDate(row.next_attempt_at),
+    lastAttemptAt: optionalDate(row.last_attempt_at),
+    appliedAt: optionalDate(row.applied_at),
+    lastErrorCode: row.last_error_code ?? undefined,
+    createdAt: new Date(row.created_at),
+    updatedAt: new Date(row.updated_at),
+  };
+}
+
+@Injectable()
+export class ExternalProjectionEnqueuer {
+  async enqueue(
+    manager: EntityManager,
+    input: ExternalProjectionIntent,
+  ): Promise<EnqueuedExternalProjection> {
+    if (
+      !manager ||
+      typeof manager.query !== 'function' ||
+      manager.queryRunner?.isTransactionActive !== true
+    ) {
+      throw new Error(
+        'External projection enqueue requires an active transaction-bound EntityManager',
+      );
+    }
+    const projectionName = requiredIdentifier(input.projectionName, 'name', 120);
+    const targetKey = requiredTargetKey(input.targetKey);
+    const operationKind = requiredIdentifier(input.operationKind, 'operation kind', 120);
+    const idempotencyKey = requiredIdentifier(input.idempotencyKey, 'idempotency key', 200);
+    const payload = canonicalizeExternalProjectionJson(input.payload);
+    const envelope = canonicalizeExternalProjectionJson({
+      operationKind,
+      payload: payload.value,
+      projectionName,
+      targetKey,
+    });
+    await manager.query(
+      `INSERT INTO external_projection_target_heads (projection_name, target_key)
+       VALUES ($1, $2)
+       ON CONFLICT (projection_name, target_key) DO NOTHING`,
+      [projectionName, targetKey],
+    );
+    const lockedTarget = rowsFromQuery<{ projection_name: string }>(
+      await manager.query(
+        `SELECT projection_name
+         FROM external_projection_target_heads
+         WHERE projection_name = $1 AND target_key = $2
+         FOR UPDATE`,
+        [projectionName, targetKey],
+      ),
+    );
+    if (lockedTarget.length !== 1) {
+      throw new Error('External projection target serialization lock was not acquired');
+    }
+    const inserted = rowsFromQuery<OperationRow>(
+      await manager.query(
+        `INSERT INTO external_projection_operations (
+          id, projection_name, target_key, operation_kind, idempotency_key, payload, payload_hash
+        ) VALUES ($1, $2, $3, $4, $5, $6::text::jsonb, $7)
+        ON CONFLICT (projection_name, idempotency_key) DO NOTHING
+        RETURNING *`,
+        [
+          randomUUID(),
+          projectionName,
+          targetKey,
+          operationKind,
+          idempotencyKey,
+          payload.text,
+          envelope.sha256,
+        ],
+      ),
+    );
+    const created = inserted[0];
+    if (created) return { operation: operationFromRow(created), created: true };
+
+    const existing = rowsFromQuery<OperationRow>(
+      await manager.query(
+        `SELECT * FROM external_projection_operations
+         WHERE projection_name = $1 AND idempotency_key = $2`,
+        [projectionName, idempotencyKey],
+      ),
+    )[0];
+    if (!existing) throw new Error('External projection idempotency lookup failed');
+    if (existing.payload_hash !== envelope.sha256) {
+      throw new ExternalProjectionIdempotencyConflictError();
+    }
+    return { operation: operationFromRow(existing), created: false };
+  }
+}

package/dist/templates/recipes/external-projection-worker/index.ts.hbs

@@ -0,0 +1,6 @@
+export * from './canonical-json';
+export * from './external-projection-enqueuer';
+export * from './external-projection-store';
+export * from './external-projection-worker';
+export * from './external-projection-worker.module';
+export * from './external-projection-worker.types';

package/dist/templates/recipes/external-projection-worker/migration.ts.hbs

@@ -0,0 +1,88 @@
+import type { MigrationInterface, QueryRunner } from 'typeorm';
+
+// Covers exponent-free PostgreSQL rendering for the canonicalizer's 10,000-node limit.
+const EXTERNAL_PROJECTION_MAX_JSONB_RENDERED_BYTES = 4_194_304;
+
+export class CreateExternalProjectionOperationsMIGRATIONTIMESTAMPPLACEHOLDER
+  implements MigrationInterface
+{
+  async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`CREATE TABLE external_projection_target_heads (
+      projection_name varchar(120) NOT NULL,
+      target_key varchar(500) NOT NULL,
+      created_at timestamptz NOT NULL DEFAULT now(),
+      PRIMARY KEY (projection_name, target_key)
+    )`);
+    await queryRunner.query(`CREATE TABLE external_projection_operations (
+      id uuid PRIMARY KEY,
+      enqueue_sequence bigint GENERATED ALWAYS AS IDENTITY UNIQUE,
+      projection_name varchar(120) NOT NULL,
+      target_key varchar(500) NOT NULL,
+      operation_kind varchar(120) NOT NULL,
+      idempotency_key varchar(200) NOT NULL,
+      payload jsonb NOT NULL,
+      payload_hash char(64) NOT NULL,
+      status varchar(20) NOT NULL DEFAULT 'pending',
+      attempt_count integer NOT NULL DEFAULT 0,
+      result_reference varchar(500),
+      lease_owner varchar(200),
+      lease_token uuid,
+      lease_expires_at timestamptz,
+      next_attempt_at timestamptz,
+      last_attempt_at timestamptz,
+      applied_at timestamptz,
+      last_error_code varchar(160),
+      created_at timestamptz NOT NULL DEFAULT now(),
+      updated_at timestamptz NOT NULL DEFAULT now(),
+      CONSTRAINT fk_external_projection_target_head
+        FOREIGN KEY (projection_name, target_key)
+        REFERENCES external_projection_target_heads (projection_name, target_key),
+      CONSTRAINT uq_external_projection_idempotency
+        UNIQUE (projection_name, idempotency_key),
+      CONSTRAINT ck_external_projection_status
+        CHECK (status IN ('pending', 'processing', 'retry_wait', 'uncertain', 'blocked', 'applied')),
+      CONSTRAINT ck_external_projection_attempts CHECK (attempt_count >= 0),
+      CONSTRAINT ck_external_projection_payload_hash
+        CHECK (payload_hash ~ '^[0-9a-f]{64}$'),
+      CONSTRAINT ck_external_projection_payload_size
+        CHECK (octet_length(payload::text) <= ${EXTERNAL_PROJECTION_MAX_JSONB_RENDERED_BYTES}),
+      CONSTRAINT ck_external_projection_lease
+        CHECK (
+          (status = 'processing' AND lease_owner IS NOT NULL AND lease_token IS NOT NULL AND lease_expires_at IS NOT NULL)
+          OR
+          (status <> 'processing' AND lease_owner IS NULL AND lease_token IS NULL AND lease_expires_at IS NULL)
+        ),
+      CONSTRAINT ck_external_projection_retry_time
+        CHECK (
+          (status IN ('retry_wait', 'uncertain') AND next_attempt_at IS NOT NULL)
+          OR
+          (status NOT IN ('retry_wait', 'uncertain') AND next_attempt_at IS NULL)
+        ),
+      CONSTRAINT ck_external_projection_applied_time
+        CHECK (
+          (status = 'applied' AND applied_at IS NOT NULL)
+          OR
+          (status <> 'applied' AND applied_at IS NULL)
+        ),
+      CONSTRAINT ck_external_projection_error
+        CHECK (
+          (status IN ('retry_wait', 'uncertain', 'blocked') AND last_error_code IS NOT NULL)
+          OR
+          (status NOT IN ('retry_wait', 'uncertain', 'blocked') AND last_error_code IS NULL)
+        )
+    )`);
+    await queryRunner.query(`CREATE INDEX ix_external_projection_dispatch
+      ON external_projection_operations (
+        projection_name, status, next_attempt_at, lease_expires_at, enqueue_sequence
+      )`);
+    await queryRunner.query(`CREATE INDEX ix_external_projection_target
+      ON external_projection_operations (
+        projection_name, target_key, enqueue_sequence, status
+      )`);
+  }
+
+  async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query('DROP TABLE external_projection_operations');
+    await queryRunner.query('DROP TABLE external_projection_target_heads');
+  }
+}

package/dist/templates/recipes/external-projection-worker/module.ts.hbs

@@ -0,0 +1,36 @@
+import { DynamicModule, Module, ModuleMetadata, Type } from '@nestjs/common';
+import { ExternalProjectionEnqueuer } from './external-projection-enqueuer';
+import { ExternalProjectionStore } from './external-projection-store';
+import {
+  EXTERNAL_PROJECTION_HANDLER,
+  EXTERNAL_PROJECTION_WORKER_OPTIONS,
+  ExternalProjectionWorker,
+  validateExternalProjectionWorkerOptions,
+} from './external-projection-worker';
+import {
+  ExternalProjectionHandler,
+  ExternalProjectionWorkerOptions,
+} from './external-projection-worker.types';
+
+@Module({})
+export class ExternalProjectionWorkerModule {
+  static register(
+    options: ExternalProjectionWorkerOptions,
+    handler: Type<ExternalProjectionHandler>,
+    imports: ModuleMetadata['imports'] = [],
+  ): DynamicModule {
+    const validated = validateExternalProjectionWorkerOptions(options);
+    return {
+      module: ExternalProjectionWorkerModule,
+      imports,
+      providers: [
+        { provide: EXTERNAL_PROJECTION_WORKER_OPTIONS, useValue: validated },
+        { provide: EXTERNAL_PROJECTION_HANDLER, useExisting: handler },
+        ExternalProjectionEnqueuer,
+        ExternalProjectionStore,
+        ExternalProjectionWorker,
+      ],
+      exports: [ExternalProjectionEnqueuer],
+    };
+  }
+}