Skip to content

Installation ​

These instructions cover published 0.3.0. Existing 0.2.0 applications should complete the migration guide before changing the dependency.

Install ​

bash
npm install @nestarc/[email protected]

Compatibility ​

Peer/runtimeDeclared range
Node.js>=20
@nestjs/common, @nestjs/core^10.0.0 or ^11.2.7
@prisma/clientOptional: ^5.0.0 or ^7.10.0
reflect-metadata^0.2.0
rxjs^7.0.0

Install the Prisma peer when using fromPrisma, PrismaRequestStorage, or the Prisma execution helpers. A custom executor/storage implementation does not need Prisma.

The release's packed PostgreSQL consumer tests exercised these exact combinations:

NestJSPrisma CLI/clientRuntime and database
10.4.225.22.0Node 24.11.1, PostgreSQL 16.15
11.2.77.10.0 with @prisma/adapter-pg 7.10.0Node 24.11.1, PostgreSQL 16.15

The package's Node range does not override its dependencies' runtime requirements. Prisma 6/8, NestJS 12, native ESM consumers, other database engines, and other combinations are outside this verification matrix. Read the release compatibility report for the exact fixtures and limits.

Prepare the schema and module ​

Follow the persistent schema and quickstart to add DataSubjectRequest, define a matching business model, run the migration, and regenerate the client. Its Prisma 5 example includes all imports, nullable personal-data fields, a shared definePolicy() definition, and DataSubjectModule.forRoot(...) registration.

Keep the policy and executor aligned:

  • Give every entity an immutable unique scalar ID for erasure verification; fromPrisma defaults to id.
  • Declare scope: { mode: 'multi-tenant', tenantField: 'tenantId' } in its definition and the same tenantField in fromPrisma.
  • List exported fields separately in exportFields; omitted or empty lists exclude that entity from export.
  • Use nullable fields for Prisma field deletion, which writes null. Run both Prisma validation and the shared-policy lint.

For an explicitly single-tenant installation, use scope: { mode: 'single-tenant', tenantId: 'installation-a' }, pass singleTenantId: 'installation-a' to both fromPrisma and the module, and use that same ID on service calls. Do not supply both tenantField and singleTenantId to the adapter.

InMemoryRequestStorage and InMemoryArtifactStorage are useful for tests. Production request history and artifacts need durable storage and explicit access/retention controls. The private artifact reference provides an S3 integration separately from the core package.

Prisma 7 setup ​

Keep the same models and shared policy. Change client generation and construction to the Prisma 7 form verified by the release. This example uses schema.prisma at the project root:

prisma
generator client {
  provider     = "prisma-client"
  output       = "./generated/client"
  moduleFormat = "cjs"
}

datasource db {
  provider = "postgresql"
}
ts
// prisma.config.ts
import { defineConfig } from 'prisma/config';

export default defineConfig({
  schema: 'schema.prisma',
  datasource: { url: process.env.DATABASE_URL! },
});
bash
npm install @prisma/[email protected] @prisma/[email protected] pg
npm install --save-dev [email protected]
npx prisma generate
ts
// Use this client in place of the Prisma 5 quickstart's client.
import { PrismaClient } from './generated/client/client';
import { PrismaPg } from '@prisma/adapter-pg';

const prisma = new PrismaClient({
  adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL! }),
});

Ensure the CLI and application process receive DATABASE_URL. Match import paths to your generated output. If you use a custom PostgreSQL schema, configure it in the adapter and in any durable store's SQL schema options.

Call the service from an application provider ​

Register this provider in your application's providers alongside the imported data-subject module:

ts
import { Injectable } from '@nestjs/common';
import { DataSubjectService } from '@nestarc/data-subject';

@Injectable()
export class PrivacyService {
  constructor(private readonly dataSubject: DataSubjectService) {}

  // The caller has already authorized this tenant, subject, actor, and action.
  exportFor(subjectId: string, tenantId: string, actorId: string) {
    return this.dataSubject.export(subjectId, tenantId, { requestedBy: actorId });
  }

  eraseFor(subjectId: string, tenantId: string, actorId: string) {
    return this.dataSubject.erase(subjectId, tenantId, { requestedBy: actorId });
  }
}

This is the immediate execution path. It does not configure a signed-preview transaction or durable idempotency. Both getRequest(id, tenantId) and getArtifact(id, tenantId) require the authorized tenant; before artifact access, the host must also authorize the request's subject. Keep listOverdue() behind privileged internal administration.

Module options ​

OptionDefaultPurpose
requestStorageRequiredRequest history; use durableStore.requests when enabling the durable path
artifactStorageRequiredZIP exports and JSON erasure evidence
definitions[]Recommended shared { definition, executor } registrations
entities[]Legacy { policy, executor } registrations remain supported
slaDays30Request deadline and overdue lookup
singleTenantIdOmittedExplicit single-tenant mode; must match executor scope
strictLegalBasisfalseValidate retention legal-basis syntax as scheme:reference
previewSigningKeyPer-instance temporary keyShared secret of at least 32 bytes for previews across instances/restarts
previewTtlMs300000Preview validity; positive and no more than one hour
allowUnverifiedfalseExplicit legacy verification compatibility; unavailable on the durable path
durableStoreOmittedDurable execution, request-key deduplication, and completion recovery
artifactRetryTtlMs24 hours per request typeDurable retry-byte lifetime through { export, erase }
publishOutbox, publishAuditOmittedLifecycle callbacks; durable delivery includes a stable delivery ID
runInTransactionOmittedImmediate erase transaction hook; all executors must use the actual transaction client

See Events & Hooks before wiring callbacks. Adding runInTransaction around root-client delegates does not make their writes transactional. Signed-preview execution requires Serializable isolation with transaction-bound executors or the configured durable path. Durable execution uses PrismaExecutionStore.bindTransaction and the same store's request storage; follow the optional durable setup.

Documentation site: MIT License. Check each package for its license.