@nest-admin/nestjs 0.11.0

package/dist/drizzle.d.ts

@@ -0,0 +1,335 @@
+/**
+ * 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;
+}
+
+/**
+ * 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>;
+}
+
+/**
+ * The Drizzle implementation of `OrmAdapter`.
+ *
+ * This package exists to answer a question the Prisma adapter cannot: is
+ * `OrmAdapter` a contract, or is it a description of Prisma? Writing a second
+ * implementation against a genuinely different ORM - a query builder with no
+ * generated client, no DMMF and no normalised errors - is the only way to find
+ * out before 1.0 freezes it.
+ *
+ * The answer, recorded here because it is the point of the package: Core needed
+ * no changes. What differs is entirely inside this directory, and each
+ * difference is documented where it is handled.
+ *
+ * ## What Drizzle does not give us, and what is done instead
+ *
+ * | Prisma | Drizzle | Handled in |
+ * | --- | --- | --- |
+ * | DMMF describing every model | the schema object itself | `schema/introspect.ts` |
+ * | `P2xxx` codes with `meta` | the driver's own error | `errors/constraints.ts` |
+ * | `mode: 'insensitive'` | `lower()` on both sides | `query/build.ts` |
+ * | escaped `contains` | escaped by hand | `query/build.ts` |
+ * | relations always named | named only if declared | `schema/introspect.ts` |
+ *
+ * ## Relations are not loaded with the record
+ *
+ * The Prisma adapter includes a to-one's target so a list can show a person's
+ * name rather than their id. Drizzle can do the same with a join, but only with
+ * the relational query API, which needs `relations()` declared - and this
+ * adapter deliberately works without them. So a to-one arrives as its foreign
+ * key, and the interface resolves the label through the relation picker, which
+ * it already does for every relation it cannot see inline.
+ */
+
+interface DrizzleAdapterOptions {
+    /** A constructed Drizzle database, from any dialect's `drizzle()`. */
+    readonly db: unknown;
+    /**
+     * The schema module.
+     *
+     * Passed separately from `db` even though `drizzle(client, { schema })` also
+     * takes it, because that form is optional and a database built without it
+     * carries nothing to introspect.
+     */
+    readonly schema: Readonly<Record<string, unknown>>;
+}
+declare class DrizzleAdapter implements OrmAdapter {
+    #private;
+    readonly name = "drizzle";
+    constructor(options: DrizzleAdapterOptions);
+    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>;
+    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>;
+}
+
+/**
+ * `ListQuery` into a Drizzle query.
+ *
+ * The rules enforced here are the ones the Prisma adapter enforces, and they
+ * are enforced again rather than shared because they are about *this* ORM's
+ * capabilities: which fields can be filtered, which operators a kind admits,
+ * what a search box searches. Where the two adapters agree, they agree because
+ * Core's contract says the same thing to both.
+ *
+ * ## Two places Drizzle needs work Prisma did for us
+ *
+ * **Case insensitivity.** Prisma has `mode: 'insensitive'`, on the providers
+ * that support it. Drizzle has `ilike`, on Postgres only. Rather than branch per
+ * dialect, both sides of the comparison go through `lower()`, which every
+ * dialect this adapter supports has. It costs an index unless one is declared on
+ * the expression - noted here because that is a real trade and not a free one.
+ *
+ * **`LIKE` metacharacters.** Prisma escapes `%` and `_` inside `contains`.
+ * Building the pattern by hand means doing it here, or a search for `100%`
+ * silently matches every row.
+ */
+
+/** Kept in step with `MAX_PER_PAGE` in the Prisma adapter and the UI's page-size list. */
+declare const DEFAULT_PER_PAGE = 25;
+declare const MAX_PER_PAGE = 100;
+
+export { DEFAULT_PER_PAGE, DrizzleAdapter, type DrizzleAdapterOptions, MAX_PER_PAGE };