@nextlyhq/adapter-drizzle 0.0.2-alpha.60 → 0.0.2-alpha.64

package/README.md

@@ -2,7 +2,31 @@
 
 Internal Drizzle ORM utilities for Nextly's database adapters.
 
-> This package is part of Nextly's internals. It is installed automatically as a dependency of [`nextly`](../nextly). Choose [`@nextlyhq/adapter-postgres`](../adapter-postgres), [`@nextlyhq/adapter-mysql`](../adapter-mysql), or [`@nextlyhq/adapter-sqlite`](../adapter-sqlite) for your project.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@nextlyhq/adapter-drizzle"><img alt="npm" src="https://img.shields.io/npm/v/@nextlyhq%2Fadapter-drizzle?style=flat-square&label=npm&color=cb3837" /></a>
+  <a href="https://github.com/nextlyhq/nextly/blob/main/LICENSE.md"><img alt="License" src="https://img.shields.io/github/license/nextlyhq/nextly?style=flat-square&color=blue" /></a>
+  <a href="https://nextlyhq.com/docs"><img alt="Status" src="https://img.shields.io/badge/status-alpha-orange?style=flat-square" /></a>
+</p>
+
+> [!IMPORTANT]
+> Nextly is in alpha. APIs may change before 1.0. Pin exact versions in production.
+
+This package is part of Nextly's internals. It is installed automatically as a dependency of [`nextly`](../nextly). Choose [`@nextlyhq/adapter-postgres`](../adapter-postgres), [`@nextlyhq/adapter-mysql`](../adapter-mysql), or [`@nextlyhq/adapter-sqlite`](../adapter-sqlite) for your project.
+
+## Install
+
+You do not install this directly. It arrives as a dependency of [`nextly`](../nextly)
+and of each database adapter. Install the adapter for your database instead:
+
+```bash
+pnpm add @nextlyhq/adapter-postgres pg
+```
+
+## Related packages
+
+- [`@nextlyhq/adapter-postgres`](../adapter-postgres) — recommended for production
+- [`@nextlyhq/adapter-mysql`](../adapter-mysql)
+- [`@nextlyhq/adapter-sqlite`](../adapter-sqlite) — local demos
 
 ## License
 

package/dist/{adapter-BG7MnOUw.d.cts → adapter-C6ENLDau.d.cts}

@@ -1,9 +1,36 @@
 import { AnyRelations, SQL } from 'drizzle-orm';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, U as UpdateOptions, D as DeleteOptions, e as UpsertOptions, f as TransactionOptions, g as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, a as Migration, d as MigrationResult } from './migration-B6AmjCQ1.cjs';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.cjs';
-import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-BUc56kip.cjs';
 import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BDn8WfSL.cjs';
 import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.cjs';
 
+/**
+ * Transaction CRUD forwarder helper for database adapters.
+ *
+ * @remarks
+ * Encapsulates the delegation pattern where a transaction context forwards its
+ * CRUD methods to the adapter's implementation while passing the transaction-bound
+ * Drizzle executor.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Interface representing an adapter that can execute CRUD operations with an optional executor.
+ */
+interface TransactionCrudDelegator {
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
+    delete(table: string, where: WhereClause, options?: DeleteOptions, executor?: unknown): Promise<number>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+}
+/**
+ * Transaction context CRUD methods provided by the forwarder.
+ */
+type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "update" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
+
 /**
  * Base database adapter abstract class.
  *
@@ -293,6 +320,23 @@ declare abstract class DrizzleAdapter {
      * for `"*"` or when nothing resolves, so callers fall back to all columns.
      */
     protected buildColumnProjection(tableObj: unknown, names: string[] | "*" | undefined): Record<string, unknown> | undefined;
+    /**
+     * The requested column names split into what this table has and what it does not.
+     *
+     * One resolution, reported both ways, because two callers need different halves
+     * of the same answer: a projection drops what it cannot find, while a distinct
+     * count has to REFUSE it. Resolving twice would let the two disagree about what
+     * "found" means — the SQL-name alias below is exactly the kind of detail a
+     * second implementation gets wrong — and the count would then reject a column
+     * the projection happily uses.
+     *
+     * Both spellings resolve: a caller may name the Drizzle property or the SQL
+     * column, and either maps to the same projection key.
+     */
+    protected resolveColumns(tableObj: unknown, names: readonly string[]): {
+        projection: Record<string, unknown>;
+        unresolved: string[];
+    };
     /**
      * Check if the adapter is currently connected.
      *
@@ -426,6 +470,51 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
+    /** The registered table object, or a refusal naming what is missing. */
+    private requireTableObject;
+    /**
+     * The columns a distinct count groups by, or `undefined` for a row count.
+     *
+     * 🔴 EVERY named column must resolve, not merely one of them. A `distinctOn`
+     * naming no column this table has would fall through to a row count, and one
+     * naming a valid column beside a misspelled or since-removed column would
+     * count distinct over a NARROWER key than the caller asked for. Both answer a
+     * different question than the one asked, silently; the second is the worse of
+     * the two, because a subset key groups more rows together and so UNDERCOUNTS,
+     * which reads as a plausible number rather than as a fault. Refused here,
+     * where the mistake was made, rather than surfacing as a wrong figure.
+     */
+    private countProjection;
+    /**
+     * `COUNT(*)` over a `SELECT DISTINCT` subquery.
+     *
+     * Its own function because it is a genuinely different query from the plain
+     * count rather than a variation on one, and because building both inline made
+     * the public method a chain of decisions the complexity gate objected to
+     * before a reader would have.
+     */
+    private countDistinctRows;
+    /** `COUNT(*)` over the table itself. */
+    private countAllRows;
+    /**
+     * How many rows match, or how many DISTINCT combinations of some columns do.
+     *
+     * The data layer had no count at all: collection totals go through
+     * `countEntries`, an access-controlled path built for collection tables, and
+     * nothing could count a system table. A caller wanting one selected the rows
+     * and measured the array, which transfers every row to learn a number and
+     * cannot be bounded without making the number wrong.
+     *
+     * 🔴 `distinctOn` compiles to `COUNT(*)` over a `SELECT DISTINCT` SUBQUERY,
+     * never to `COUNT(DISTINCT a, b)`. The inline form is not portable and fails
+     * in the direction that is hardest to notice -- MySQL accepts it, PostgreSQL
+     * needs a row constructor, and SQLite rejects it outright with "wrong number
+     * of arguments to function count()" -- so a query written against one engine
+     * is a syntax error on another. The subquery is the single form all three
+     * accept, and building it here rather than at each call site is what keeps
+     * the answer identical per dialect.
+     */
+    count(table: string, options?: CountOptions, executor?: unknown): Promise<number>;
     selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
     /**
      * Insert a single record into a table.
@@ -708,12 +797,35 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createDatabaseError(kind: DatabaseErrorKind, message: string, cause?: Error): DatabaseError;
+    /**
+     * Helper to create transaction context CRUD forwarding methods.
+     *
+     * @param txDb - Thunk returning the transaction-bound Drizzle executor
+     * @returns Object providing forwarded CRUD and getDrizzle methods
+     *
+     * @protected
+     */
+    protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * Classify an error into a DatabaseError.
+     *
+     * @remarks
+     * Subclasses can override this method to add dialect-specific error code classification.
+     *
+     * @param error - Original error
+     * @param sql - SQL statement that caused the error (optional)
+     * @returns DatabaseError instance
+     *
+     * @protected
+     */
+    protected classifyError(error: unknown, sql?: string): DatabaseError;
     /**
      * Handle query errors and convert to DatabaseError.
      *
      * @remarks
      * Protected helper for consistent error handling across CRUD operations.
-     * Subclasses can override to add dialect-specific error classification.
+     * Delegates to `classifyError` and attaches operation and table context if not present.
+     * Subclasses override `classifyError` to provide dialect-specific error code classification.
      *
      * @param error - Original error
      * @param operation - Operation that failed
@@ -725,4 +837,4 @@ declare abstract class DrizzleAdapter {
     protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
 }
 
-export { DrizzleAdapter as D };
+export { DrizzleAdapter as D, type TransactionCrudDelegator as T, type TransactionCrudForwarders as a };

package/dist/{adapter-DjPoLjBK.d.ts → adapter-D4GM1VAZ.d.ts}

@@ -1,9 +1,36 @@
 import { AnyRelations, SQL } from 'drizzle-orm';
+import { T as TransactionContext, S as SelectOptions, W as WhereClause, U as UpdateOptions, D as DeleteOptions, e as UpsertOptions, f as TransactionOptions, g as DatabaseCapabilities, P as PoolStats, C as CountOptions, I as InsertOptions, a as Migration, d as MigrationResult } from './migration-R06fsTrz.js';
 import { S as SupportedDialect, a as SqlParam, T as TableResolver } from './core-CVO7WYDj.js';
-import { T as TransactionContext, e as TransactionOptions, D as DatabaseCapabilities, P as PoolStats, S as SelectOptions, I as InsertOptions, W as WhereClause, U as UpdateOptions, f as DeleteOptions, g as UpsertOptions, a as Migration, d as MigrationResult } from './migration-Bj84e15B.js';
 import { T as TableDefinition, C as CreateTableOptions, D as DropTableOptions, A as AlterTableOperation, a as AlterTableOptions } from './schema-BIQ0YQZ_.js';
 import { D as DatabaseErrorKind, a as DatabaseError } from './error-BrdknH2s.js';
 
+/**
+ * Transaction CRUD forwarder helper for database adapters.
+ *
+ * @remarks
+ * Encapsulates the delegation pattern where a transaction context forwards its
+ * CRUD methods to the adapter's implementation while passing the transaction-bound
+ * Drizzle executor.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Interface representing an adapter that can execute CRUD operations with an optional executor.
+ */
+interface TransactionCrudDelegator {
+    select<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T[]>;
+    selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
+    update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions, executor?: unknown): Promise<T[]>;
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause, executor?: unknown): Promise<number>;
+    delete(table: string, where: WhereClause, options?: DeleteOptions, executor?: unknown): Promise<number>;
+    upsert<T = unknown>(table: string, data: Record<string, unknown>, options: UpsertOptions, executor?: unknown): Promise<T>;
+}
+/**
+ * Transaction context CRUD methods provided by the forwarder.
+ */
+type TransactionCrudForwarders = Pick<TransactionContext, "select" | "selectOne" | "update" | "updateCount" | "delete" | "upsert" | "getDrizzle">;
+
 /**
  * Base database adapter abstract class.
  *
@@ -293,6 +320,23 @@ declare abstract class DrizzleAdapter {
      * for `"*"` or when nothing resolves, so callers fall back to all columns.
      */
     protected buildColumnProjection(tableObj: unknown, names: string[] | "*" | undefined): Record<string, unknown> | undefined;
+    /**
+     * The requested column names split into what this table has and what it does not.
+     *
+     * One resolution, reported both ways, because two callers need different halves
+     * of the same answer: a projection drops what it cannot find, while a distinct
+     * count has to REFUSE it. Resolving twice would let the two disagree about what
+     * "found" means — the SQL-name alias below is exactly the kind of detail a
+     * second implementation gets wrong — and the count would then reject a column
+     * the projection happily uses.
+     *
+     * Both spellings resolve: a caller may name the Drizzle property or the SQL
+     * column, and either maps to the same projection key.
+     */
+    protected resolveColumns(tableObj: unknown, names: readonly string[]): {
+        projection: Record<string, unknown>;
+        unresolved: string[];
+    };
     /**
      * Check if the adapter is currently connected.
      *
@@ -426,6 +470,51 @@ declare abstract class DrizzleAdapter {
      * });
      * ```
      */
+    /** The registered table object, or a refusal naming what is missing. */
+    private requireTableObject;
+    /**
+     * The columns a distinct count groups by, or `undefined` for a row count.
+     *
+     * 🔴 EVERY named column must resolve, not merely one of them. A `distinctOn`
+     * naming no column this table has would fall through to a row count, and one
+     * naming a valid column beside a misspelled or since-removed column would
+     * count distinct over a NARROWER key than the caller asked for. Both answer a
+     * different question than the one asked, silently; the second is the worse of
+     * the two, because a subset key groups more rows together and so UNDERCOUNTS,
+     * which reads as a plausible number rather than as a fault. Refused here,
+     * where the mistake was made, rather than surfacing as a wrong figure.
+     */
+    private countProjection;
+    /**
+     * `COUNT(*)` over a `SELECT DISTINCT` subquery.
+     *
+     * Its own function because it is a genuinely different query from the plain
+     * count rather than a variation on one, and because building both inline made
+     * the public method a chain of decisions the complexity gate objected to
+     * before a reader would have.
+     */
+    private countDistinctRows;
+    /** `COUNT(*)` over the table itself. */
+    private countAllRows;
+    /**
+     * How many rows match, or how many DISTINCT combinations of some columns do.
+     *
+     * The data layer had no count at all: collection totals go through
+     * `countEntries`, an access-controlled path built for collection tables, and
+     * nothing could count a system table. A caller wanting one selected the rows
+     * and measured the array, which transfers every row to learn a number and
+     * cannot be bounded without making the number wrong.
+     *
+     * 🔴 `distinctOn` compiles to `COUNT(*)` over a `SELECT DISTINCT` SUBQUERY,
+     * never to `COUNT(DISTINCT a, b)`. The inline form is not portable and fails
+     * in the direction that is hardest to notice -- MySQL accepts it, PostgreSQL
+     * needs a row constructor, and SQLite rejects it outright with "wrong number
+     * of arguments to function count()" -- so a query written against one engine
+     * is a syntax error on another. The subquery is the single form all three
+     * accept, and building it here rather than at each call site is what keeps
+     * the answer identical per dialect.
+     */
+    count(table: string, options?: CountOptions, executor?: unknown): Promise<number>;
     selectOne<T = unknown>(table: string, options?: SelectOptions, executor?: unknown): Promise<T | null>;
     /**
      * Insert a single record into a table.
@@ -708,12 +797,35 @@ declare abstract class DrizzleAdapter {
      * @protected
      */
     protected createDatabaseError(kind: DatabaseErrorKind, message: string, cause?: Error): DatabaseError;
+    /**
+     * Helper to create transaction context CRUD forwarding methods.
+     *
+     * @param txDb - Thunk returning the transaction-bound Drizzle executor
+     * @returns Object providing forwarded CRUD and getDrizzle methods
+     *
+     * @protected
+     */
+    protected createTransactionForwarders(txDb: () => unknown): TransactionCrudForwarders;
+    /**
+     * Classify an error into a DatabaseError.
+     *
+     * @remarks
+     * Subclasses can override this method to add dialect-specific error code classification.
+     *
+     * @param error - Original error
+     * @param sql - SQL statement that caused the error (optional)
+     * @returns DatabaseError instance
+     *
+     * @protected
+     */
+    protected classifyError(error: unknown, sql?: string): DatabaseError;
     /**
      * Handle query errors and convert to DatabaseError.
      *
      * @remarks
      * Protected helper for consistent error handling across CRUD operations.
-     * Subclasses can override to add dialect-specific error classification.
+     * Delegates to `classifyError` and attaches operation and table context if not present.
+     * Subclasses override `classifyError` to provide dialect-specific error code classification.
      *
      * @param error - Original error
      * @param operation - Operation that failed
@@ -725,4 +837,4 @@ declare abstract class DrizzleAdapter {
     protected handleQueryError(error: unknown, operation: string, table: string): DatabaseError;
 }
 
-export { DrizzleAdapter as D };
+export { DrizzleAdapter as D, type TransactionCrudDelegator as T, type TransactionCrudForwarders as a };