@nest-admin/nestjs 0.11.0

package/dist/prisma.d.ts

@@ -0,0 +1,585 @@
+/**
+ * Normalised, ORM-independent description of a model and its fields.
+ *
+ * Every ORM adapter translates its own schema representation (Prisma DMMF,
+ * TypeORM entity metadata, a Drizzle table object, ...) into these shapes.
+ * Nothing downstream - the CRUD engine, the HTTP API, the admin UI - is
+ * allowed to look at anything else.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+/** ORM-independent classification of a scalar or relation field. */
+type FieldKind = 'string' | 'number' | 'boolean' | 'datetime' | 'enum' | 'json' | 'relation'
+/** The adapter recognised the field but cannot map it onto a known kind. */
+ | 'unknown';
+/** Cardinality of a relation from the owning model's point of view. */
+type RelationCardinality = 'one' | 'many';
+/**
+ * A relation, and how to act on it.
+ *
+ * `from` and `to` are what turn a relation from something an admin can only
+ * display into something it can filter and write. A to-one relation is stored
+ * as an ordinary scalar column - `Post.authorId` - and that column is what a
+ * query has to be expressed in terms of. Without knowing its name, a filter on
+ * `author` cannot be translated, and a form has no field to submit.
+ *
+ * Both are absent on to-many relations, which have no column on this side.
+ */
+interface RelationMetadata {
+    /** `name` of the {@link ModelMetadata} on the other side of the relation. */
+    readonly targetModel: string;
+    readonly cardinality: RelationCardinality;
+    /**
+     * Scalar field on **this** model holding the foreign key, for a to-one
+     * relation - `authorId` on `Post.author`.
+     *
+     * Absent when the relation has no column on this side: every to-many, and
+     * the non-owning half of a one-to-one.
+     */
+    readonly from?: string;
+    /** Field on the target model that `from` points at - usually its id. */
+    readonly to?: string;
+    /**
+     * Name shared by both halves of the relation.
+     *
+     * The only reliable way to pair `User.posts` with `Post.author`, which two
+     * things need. Distinguishing a many-to-many from a one-to-many requires
+     * looking at the other side - both are `'many'` from here, but only one has
+     * no column anywhere. And knowing whether a child's key is required decides
+     * whether it can be detached at all.
+     *
+     * Two relations between the same pair of models are told apart by it too:
+     * `Post.author` and `Post.reviewer` both target `User`.
+     */
+    readonly name?: string;
+}
+interface FieldMetadata {
+    readonly name: string;
+    readonly kind: FieldKind;
+    /** Part of the model's primary key. */
+    readonly isId: boolean;
+    readonly isRequired: boolean;
+    readonly isUnique: boolean;
+    /** The field holds a list of {@link FieldKind} values. */
+    readonly isList: boolean;
+    /**
+     * The value is produced by the database or the ORM and is not asked of the
+     * user - `@default(cuid())`, `@default(now())`, `@default(autoincrement())`,
+     * `@updatedAt`. Such fields are displayed but not editable.
+     *
+     * This is NOT "has a default". A field with a literal default
+     * (`active Boolean @default(true)`) is an ordinary editable field that
+     * happens to arrive pre-filled; see {@link FieldMetadata.defaultValue}.
+     *
+     * NAME COLLISION - read before implementing an adapter. Prisma's DMMF also
+     * has a field called `isGenerated`, and it does NOT mean this. Measured
+     * against Prisma 7.10.0, DMMF reports `isGenerated: false` for
+     * `id String @id @default(cuid())`. Mapping it across directly produces
+     * editable primary keys. The correct derivation - a *function* default, or
+     * an updated-at column - is in `packages/prisma/src/metadata/to-metadata.ts`
+     * and `packages/drizzle/src/metadata/to-metadata.ts`, which state it in each
+     * ORM's own terms.
+     */
+    readonly isGenerated: boolean;
+    /**
+     * Accepted on a write, never returned on a read.
+     *
+     * Set by `writeOnly` in the configuration. A password is the reason it
+     * exists: it has to be typed into a form and must never come back out, and
+     * `hidden` cannot express that - it refuses the field in both directions, so
+     * a hidden password column leaves no way to set one.
+     *
+     * Enforced twice, deliberately: the field is left out of the columns the
+     * adapter is asked for, *and* out of the projection applied to whatever comes
+     * back. One of those is enough; two is what it takes for a future adapter
+     * that ignores the field scope not to become a leak.
+     */
+    readonly writeOnly?: boolean;
+    /**
+     * Literal default the admin should pre-fill on create, when the schema
+     * declares one (`@default(true)`, `@default(0)`, `@default("USER")`).
+     *
+     * Absent for generated values: there is no literal to pre-fill for
+     * `@default(now())`, and {@link FieldMetadata.isGenerated} is `true` instead.
+     */
+    readonly defaultValue?: unknown;
+    /** Populated when `kind` is `'enum'`. */
+    readonly enumValues?: readonly string[];
+    /** Populated when `kind` is `'relation'`. */
+    readonly relation?: RelationMetadata;
+}
+interface ModelMetadata {
+    /** Adapter-facing identifier, e.g. the Prisma model name `User`. */
+    readonly name: string;
+    /**
+     * Field names forming the primary key. Modelled as a list rather than a
+     * single `id` so composite keys do not require a breaking change later,
+     * even though the MVP will only support single-column keys.
+     */
+    readonly primaryKey: readonly string[];
+    readonly fields: readonly FieldMetadata[];
+    /**
+     * Field that names a record of this model in one line, when the application
+     * has declared one.
+     *
+     * A slot rather than a value: left unset, `displayFieldFor` works it out from
+     * the fields. It is here so that a declared choice travels with the model and
+     * reaches the adapter and the metadata document alike, without either of them
+     * having to read configuration.
+     */
+    readonly displayField?: string;
+}
+
+/**
+ * Where admin accounts live, as a contract.
+ *
+ * ## Why this exists at all
+ *
+ * Until 0.9.0 the answer to "who may open the admin?" was always the host
+ * application's: it already had sessions, and `AdminAuth` asked it one
+ * question. That is still right for a team that has an identity system, and
+ * nothing about it changes.
+ *
+ * It is a wall for everyone else. An application with no login of its own had
+ * to write a password hash, a session cookie and a form before the admin could
+ * go anywhere near production - which is a strange thing to ask of a package
+ * whose whole claim is that you do not build an admin.
+ *
+ * ## Why it is a contract rather than a table
+ *
+ * The same reason `OrmAdapter` is. An admin whose accounts can only live in
+ * Prisma has learned about Prisma, and the second ORM would find out the hard
+ * way. Everything here is plain data and promises; nothing knows what a
+ * database is.
+ *
+ * ## These accounts are not the application's users
+ *
+ * Deliberately, and this is the point most worth getting right. The people who
+ * administer a system are usually not rows in the table they administer, and
+ * conflating the two means a customer record with a password that opens the
+ * admin. The store is separate storage - a different model, or a different
+ * database entirely - and the admin never reads or writes the application's
+ * own users to decide who may sign in.
+ */
+/** One account that may sign in to the admin. */
+interface AdminAccount {
+    readonly id: string;
+    /**
+     * What is typed into the login form.
+     *
+     * Called `email` because that is what it almost always is, and a name people
+     * recognise is worth more than one that covers a case nobody has. A store is
+     * free to hold usernames in it.
+     */
+    readonly email: string;
+    /** Shown in the interface. Falls back to the email when absent. */
+    readonly name?: string | undefined;
+    /**
+     * The stored password hash, in whatever form the hasher produced.
+     *
+     * Read by the sign-in check and by nothing else. It must never reach a
+     * response, and the account the interface is told about is a projection that
+     * does not include it.
+     */
+    readonly passwordHash: string;
+    /**
+     * Suspended without being deleted.
+     *
+     * Distinct from removing the row: an account that has done things is worth
+     * keeping for the record, and "cannot sign in" is not the same fact as
+     * "never existed".
+     */
+    readonly disabled?: boolean | undefined;
+}
+/**
+ * How the admin reaches its accounts.
+ *
+ * Read-only by design. Creating and editing accounts is the application's
+ * business: it owns the storage, it knows whether that is a migration, a seed
+ * script or a form somewhere else, and an admin that could mint its own
+ * administrators is an escalation waiting for its first mistake.
+ */
+interface AdminAccountStore {
+    /**
+     * Find an account by what was typed into the login form.
+     *
+     * Matching is the store's decision, and it should be case-insensitive on the
+     * local part in practice: someone who registered as `Ada@example.com` will
+     * type `ada@example.com` eventually.
+     *
+     * Returns `null` when there is none. The caller must not behave observably
+     * differently for `null` than for a wrong password - see the sign-in code.
+     */
+    findByEmail(email: string): Promise<AdminAccount | null>;
+    /**
+     * Find an account by its id, for a request that arrives with a session.
+     *
+     * Called on every authenticated request, so it should be cheap. It is also
+     * what makes a disabled or deleted account stop working immediately rather
+     * than when its session happens to expire.
+     */
+    findById(id: string): Promise<AdminAccount | null>;
+    /**
+     * How many accounts exist.
+     *
+     * Used once, at startup, to say so when the answer is zero - an admin nobody
+     * can sign in to is a configuration mistake that otherwise announces itself
+     * as a login form that rejects everything.
+     */
+    count(): Promise<number>;
+    /**
+     * Note that an account signed in. Optional.
+     *
+     * A store that does not care about this can leave it out; the sign-in path
+     * does not wait for it and a failure is logged rather than surfaced, because
+     * "your login worked but we could not write down that it did" is not
+     * something the person signing in can act on.
+     */
+    recordLogin?(id: string): Promise<void>;
+    /**
+     * What this store reads, for diagnostics. Optional.
+     *
+     * A model name, a table, a directory - whatever names the storage in a way a
+     * person would recognise. It exists so a startup check can say something
+     * useful rather than something generic: an admin that exposes its own
+     * account model as an editable resource is an escalation, and a warning that
+     * cannot name the model is a warning nobody acts on.
+     *
+     * Never used to decide anything, and never sent to a client.
+     */
+    readonly describes?: string;
+}
+
+/**
+ * ORM-independent query description.
+ *
+ * The admin UI and the HTTP layer speak only this vocabulary; each adapter is
+ * responsible for translating it into its own query language.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+type SortDirection = 'asc' | 'desc';
+interface SortRule {
+    readonly field: string;
+    readonly direction: SortDirection;
+}
+/**
+ * The deliberately small operator set the MVP targets. Anything richer
+ * (nested relation filters, OR/AND trees, full-text) is a later concern and
+ * should extend this union rather than bypass it.
+ */
+type FilterOperator = 'eq' | 'ne' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+interface FilterRule {
+    readonly field: string;
+    readonly operator: FilterOperator;
+    readonly value: unknown;
+}
+/** Page-number based pagination. Cursor pagination is a later addition. */
+interface ListQuery {
+    readonly page?: number;
+    readonly perPage?: number;
+    readonly sort?: readonly SortRule[];
+    readonly filters?: readonly FilterRule[];
+    /** Free-text term the adapter applies across searchable string fields. */
+    readonly search?: string;
+    /**
+     * The fields this query may touch, and the only ones it should return.
+     *
+     * Set by the caller that knows which fields the admin exposes - the adapter
+     * reads a schema, not a configuration. Without it, a field the application
+     * hid would still be searched by free text, sortable, filterable and
+     * returned, because from the adapter's side it is an ordinary column.
+     *
+     * Omitted means "every field the model has".
+     */
+    readonly fields?: readonly string[];
+}
+interface Page<T> {
+    readonly data: readonly T[];
+    readonly total: number;
+    readonly page: number;
+    readonly perPage: number;
+}
+
+/**
+ * The single seam between Nest Admin and any ORM.
+ *
+ * Adding support for a new ORM means writing one implementation of
+ * {@link OrmAdapter} and nothing else. Core, the NestJS integration, the HTTP
+ * contract and the admin UI stay untouched.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+
+/**
+ * Primary key value of a single record. Composite keys are represented by
+ * {@link ModelMetadata.primaryKey}; supporting them at this level is a
+ * post-MVP change.
+ */
+type RecordId = string | number;
+/** An untyped record as it crosses the adapter boundary. */
+type RecordData = Record<string, unknown>;
+interface OrmAdapter {
+    /** Stable identifier used in diagnostics, e.g. `'prisma'`. */
+    readonly name: string;
+    /**
+     * Discover the models the adapter can serve. Asynchronous because an adapter
+     * may need to read a schema file or import a generated client.
+     */
+    getModels(): Promise<readonly ModelMetadata[]>;
+    list(model: string, query: ListQuery): Promise<Page<RecordData>>;
+    findOne(model: string, id: RecordId): Promise<RecordData | null>;
+    create(model: string, data: RecordData): Promise<RecordData>;
+    update(model: string, id: RecordId, data: RecordData): Promise<RecordData>;
+    delete(model: string, id: RecordId): Promise<void>;
+    /**
+     * A page of the records on the far side of a to-many relation.
+     *
+     * Paginated for the same reason a list is: the number of children is a
+     * property of the data, not of the schema, and a parent with fifty thousand
+     * of them must not be a page that never loads.
+     *
+     * Kept separate from `list` rather than expressed as a filter because a
+     * many-to-many has no column to filter on - the link lives in a join table.
+     * A one-to-many could be asked for either way; going through one method means
+     * the caller does not have to know which it is looking at.
+     */
+    listRelated(model: string, id: RecordId, relationField: string, query: ListQuery): Promise<Page<RecordData>>;
+    /**
+     * Link an existing record to this one.
+     *
+     * Across a many-to-many this adds a row to the join table and changes
+     * neither record. Across a one-to-many it rewrites the child's foreign key,
+     * which also **removes it from whatever parent held it** - the same operation
+     * with a consequence the caller should have been told about. Deciding whether
+     * to warn is the transport layer's job; the adapter performs what it is asked.
+     */
+    attachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+    /**
+     * Unlink a record from this one, without deleting either.
+     *
+     * Across a one-to-many this clears the child's foreign key, which is
+     * impossible when that column is required - see `detachBlockedReason`. The
+     * adapter may assume the caller has checked, and will surface the database's
+     * own refusal if it has not.
+     */
+    detachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+}
+
+/**
+ * Framework error vocabulary.
+ *
+ * Deliberately small. These exist so that adapters raise ORM-independent
+ * errors and the transport layer can map them to status codes without knowing
+ * which ORM produced them. Resist growing this taxonomy - add a new type only
+ * when a caller genuinely needs to branch on it.
+ *
+ * ## Why these are not identified with `instanceof`
+ *
+ * A published bundle can contain more than one copy of this module. The
+ * package ships two CommonJS entrypoints and each inlines its own copy of
+ * Core, so an error thrown inside the Prisma adapter is an instance of a
+ * *different* `FieldNotFoundError` class than the one the exception filter
+ * holds. `instanceof` compares class identity, so it answered `false` and
+ * every adapter-raised error was mapped to a generic 500 - a caller who
+ * mistyped a sort field got "internal error" instead of "unknown field".
+ *
+ * That was invisible to this repository's own tests, which resolve Core to a
+ * single source module, and only appeared when the built package was installed
+ * and run. So errors are identified by *value* rather than identity: a
+ * `Symbol.for` brand, which duplicate copies agree on by definition, plus a
+ * stable `kind` string. Neither depends on which copy created the object.
+ *
+ * `scripts/verify-packed-consumer.mjs` asserts the arrangement every release:
+ * one shared copy in ESM, one per entrypoint in CJS. If that ever changes, the
+ * count changes there first.
+ *
+ * @experimental Draft contract. Expected to change during MVP implementation.
+ */
+/**
+ * Stable discriminator for each error type.
+ *
+ * A declared string rather than the class, so it survives duplicate bundles,
+ * and rather than `name`, so it survives minification.
+ */
+type AdminErrorKind = 'unauthorized' | 'forbidden' | 'model-not-found' | 'field-not-found' | 'record-not-found' | 'invalid-query'
+/** Application code refused the input. Its message reaches the client. */
+ | 'validation'
+/** The database refused the write: unique, foreign key, or required. */
+ | 'constraint' | 'adapter'
+/** A subclass that declared no kind of its own. Treated as internal. */
+ | 'unknown';
+/**
+ * Base error type. Every error raised by Nest Admin extends it so that the
+ * NestJS integration can distinguish framework errors from application errors
+ * without depending on concrete subclasses.
+ */
+declare class NestAdminError extends Error {
+    /**
+     * Which error this is.
+     *
+     * Subclasses override it with a literal. The base value covers anything that
+     * extends this class without declaring one - the Prisma schema errors, for
+     * instance - which the transport layer treats as internal.
+     */
+    readonly kind: AdminErrorKind;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * `PrismaAdapter` - the Prisma implementation of Core's `OrmAdapter`.
+ *
+ * The adapter never constructs a Prisma Client. Prisma 7 builds clients from
+ * driver adapters, so only the consuming application knows the provider, the
+ * credentials and the connection strategy. We receive a constructed client and
+ * use it.
+ */
+
+interface PrismaAdapterOptions {
+    /**
+     * A constructed Prisma Client. Owned entirely by the consuming application:
+     * the adapter never calls `new PrismaClient()`, because under Prisma 7 the
+     * client is built from a driver adapter that only the application can supply.
+     */
+    readonly client: unknown;
+    /**
+     * Path to `schema.prisma`, or to a directory of `.prisma` files. When
+     * omitted, `prisma/schema.prisma`, `prisma/schema` and `schema.prisma` are
+     * tried in that order, relative to `cwd`.
+     */
+    readonly schemaPath?: string;
+    /** Base directory for schema resolution. Defaults to `process.cwd()`. */
+    readonly cwd?: string;
+}
+declare class PrismaAdapter implements OrmAdapter {
+    #private;
+    readonly name = "prisma";
+    constructor(options: PrismaAdapterOptions);
+    getModels(): Promise<readonly ModelMetadata[]>;
+    list(model: string, query: ListQuery): Promise<Page<RecordData>>;
+    findOne(model: string, id: RecordId): Promise<RecordData | null>;
+    create(model: string, data: RecordData): Promise<RecordData>;
+    update(model: string, id: RecordId, data: RecordData): Promise<RecordData>;
+    delete(model: string, id: RecordId): Promise<void>;
+    /**
+     * A page of the records on the far side of a to-many relation.
+     *
+     * Implemented as an ordinary list of the *target* model with one extra
+     * condition, so pagination, sorting, filtering and relation loading all
+     * behave exactly as they do on a top-level list. See `to-related-where.ts`.
+     */
+    listRelated(model: string, id: RecordId, relationField: string, query: ListQuery): Promise<Page<RecordData>>;
+    attachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+    detachRelated(model: string, id: RecordId, relationField: string, targetId: RecordId): Promise<void>;
+}
+
+/** Raised when the Prisma schema cannot be located or read. */
+declare class PrismaSchemaNotFoundError extends NestAdminError {
+    readonly triedPaths: readonly string[];
+    constructor(triedPaths: readonly string[], explicit: boolean);
+}
+/** Raised when Prisma rejects the schema. Carries Prisma's own validation text. */
+declare class PrismaSchemaInvalidError extends NestAdminError {
+    readonly prismaMessage: string;
+    constructor(prismaMessage: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/**
+ * Prisma version gate.
+ *
+ * Phase 1 established that `@prisma/get-dmmf` is pinned exactly and enforces
+ * *its own* Prisma version's schema rules: given a Prisma 6 schema, the 7.x
+ * parser rejects `url` inside `datasource` even though the schema is perfectly
+ * valid for that consumer. Without a gate, that surfaces as a confusing
+ * "Prisma rejected the schema" error pointing at the user's own valid file.
+ *
+ * The gate turns that into a statement about versions.
+ *
+ * ## Two deliberate design choices
+ *
+ * **It fails open on detection.** The client version is read from
+ * `client._clientVersion`, an underscore-prefixed internal. If Prisma renames
+ * or removes it, the gate silently does nothing rather than breaking every
+ * consumer on an otherwise-fine upgrade. A version check that itself becomes
+ * the outage is worse than no version check.
+ *
+ * **It compares majors only.** Minor and patch releases have not changed the
+ * schema language; majors have. Pinning tighter would produce false alarms on
+ * every routine bump.
+ *
+ * This lives in `packages/prisma`, not Core - Core must never learn what
+ * Prisma is.
+ */
+
+/** Raised when the consumer's Prisma Client major is outside the tested range. */
+declare class PrismaVersionUnsupportedError extends NestAdminError {
+    readonly clientVersion: string;
+    readonly supportedMajors: readonly number[];
+    constructor(clientVersion: string, supportedMajors: readonly number[]);
+}
+
+/**
+ * Admin accounts, in Prisma.
+ *
+ * ## A model of its own
+ *
+ * The default is `AdminAccount`, and that default is the design rather than a
+ * placeholder. The people who administer a system are usually not rows in the
+ * table they administer, and pointing this at the application's `User` would
+ * mean every customer record carries a password that opens the admin - which is
+ * a decision nobody makes on purpose and several people make by accident.
+ *
+ * The model name is configurable because some applications already have a
+ * `Staff` or an `Operator`. Pointing it at `User` is possible and is a choice,
+ * not a default.
+ *
+ * ## What it does not do
+ *
+ * Create, update, delete. The store contract is read-only, and this implements
+ * only what it declares: an admin that could mint its own administrators is an
+ * escalation waiting for its first mistake in a policy. Seeding the first
+ * account is the application's job, with `hashAdminPassword`.
+ *
+ * ## The account model should not be a resource
+ *
+ * Nothing here can arrange that - which models the admin exposes is the
+ * module's business - so it is the one thing a consumer has to remember:
+ *
+ * ```ts
+ * resources: { exclude: ['AdminAccount'] }
+ * ```
+ *
+ * Without it, anyone who may edit that model can grant themselves whatever the
+ * admin can do. `builtInAuth` warns at startup when it sees the account model
+ * among the exposed resources.
+ */
+
+interface PrismaAccountStoreOptions {
+    /** A constructed Prisma Client - the same one the adapter is given. */
+    readonly client: unknown;
+    /** The model holding admin accounts. `AdminAccount` by default. */
+    readonly model?: string;
+    /**
+     * Column names, where they differ from the defaults.
+     *
+     * A mapping rather than a required schema: an application that already has a
+     * `Staff` table with `login` and `hash` should not have to migrate it to use
+     * this.
+     */
+    readonly fields?: {
+        readonly id?: string;
+        readonly email?: string;
+        readonly name?: string;
+        readonly passwordHash?: string;
+        readonly disabled?: string;
+        /** Written on a successful sign-in, when the column exists. */
+        readonly lastLoginAt?: string;
+    };
+}
+declare function prismaAccountStore(options: PrismaAccountStoreOptions): AdminAccountStore;
+
+export { type PrismaAccountStoreOptions, PrismaAdapter, type PrismaAdapterOptions, PrismaSchemaInvalidError, PrismaSchemaNotFoundError, PrismaVersionUnsupportedError, prismaAccountStore };