@nextlyhq/adapter-drizzle 0.0.2-alpha.6 → 0.0.2-alpha.62

package/dist/{migration-Qe70wDOC.d.ts → migration-BnT96HFp.d.ts}

@@ -1,4 +1,5 @@
 import { a as SqlParam, S as SupportedDialect } from './core-CVO7WYDj.js';
+import { SQL } from 'drizzle-orm';
 
 /**
  * Query building type definitions for database-agnostic queries.
@@ -7,19 +8,42 @@ import { a as SqlParam, S as SupportedDialect } from './core-CVO7WYDj.js';
  */
 
 /**
- * Supported WHERE clause operators.
+ * Every WHERE clause operator this package DECLARES, as a value.
  *
  * @remarks
+ * Declared, not guaranteed executable. Membership here means a `WhereCondition`
+ * carrying the operator type-checks — it does NOT mean the adapter can run it.
+ * `OVERLAPS` is declared and unimplemented, and throws at build time, so a
+ * validator written against this list will admit input the query layer then
+ * rejects. Validate against it to catch a misspelled operator; do not read
+ * acceptance here as a capability.
+ *
  * - Standard comparison: =, !=, <, >, <=, >=
  * - Set operations: IN, NOT IN
  * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)
  * - NULL checks: IS NULL, IS NOT NULL
  * - Range: BETWEEN, NOT BETWEEN
- * - JSON/Array: CONTAINS, OVERLAPS
+ * - Substring: CONTAINS — a LITERAL match on a TEXT column; see below
+ * - Declared but NOT implemented: OVERLAPS, which throws
+ *
+ * This list is the source of truth and {@link WhereOperator} is derived from it,
+ * rather than the two being written out separately. A guard that has to enumerate
+ * the operators — a validator over caller input, or a test asserting the builder
+ * handles or refuses each one — can only do that from a runtime value, and a
+ * hand-kept copy of the union would agree with it on the day it was written and
+ * silently stop agreeing the next time a member is added.
+ *
+ * @public
+ */
+declare const WHERE_OPERATORS: readonly ["=", "!=", "<", ">", "<=", ">=", "IN", "NOT IN", "LIKE", "ILIKE", "IS NULL", "IS NOT NULL", "BETWEEN", "NOT BETWEEN", "CONTAINS", "OVERLAPS"];
+/**
+ * Every WHERE clause operator this package declares. Derived from
+ * {@link WHERE_OPERATORS}, and carrying the same caveat: a value of this type
+ * type-checks, which is not the same as the adapter being able to execute it.
  *
  * @public
  */
-type WhereOperator = "=" | "!=" | "<" | ">" | "<=" | ">=" | "IN" | "NOT IN" | "LIKE" | "ILIKE" | "IS NULL" | "IS NOT NULL" | "BETWEEN" | "NOT BETWEEN" | "CONTAINS" | "OVERLAPS";
+type WhereOperator = (typeof WHERE_OPERATORS)[number];
 /**
  * Individual WHERE condition.
  *
@@ -147,6 +171,17 @@ interface SelectOptions {
     having?: WhereClause;
     /** Return distinct rows only */
     distinct?: boolean;
+    /**
+     * Take a `FOR UPDATE` row lock on the selected rows for the rest of the
+     * transaction, and read the latest committed values rather than the
+     * transaction's snapshot. Use for read-modify-write sequences that must not
+     * interleave (e.g. re-reading a status under the lock the write will take).
+     *
+     * Requires a transaction executor. No-ops on SQLite, which has no `FOR UPDATE`
+     * and needs none — its transactions open with `BEGIN IMMEDIATE`, already
+     * serializing writers.
+     */
+    forUpdate?: boolean;
 }
 /**
  * Options for INSERT operations.
@@ -275,6 +310,58 @@ interface TransactionContext {
      * @returns Array of result rows
      */
     execute<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+    /**
+     * Run a Drizzle-built statement within the transaction, for its effect.
+     *
+     * @remarks
+     * The typed CRUD methods below resolve their table through the schema
+     * registry and reject any name it does not declare. That leaves no way to
+     * write to a table addressed under a name the ORM does not know — a table
+     * mid-rename, most of all — other than assembling SQL by hand, which also
+     * means hand-picking each driver's placeholder syntax.
+     *
+     * This accepts Drizzle's `sql` template instead, so identifier quoting and
+     * parameter binding are generated for the dialect in use. Implemented per
+     * adapter because the underlying call is not uniform: node-postgres and
+     * mysql2 expose `execute`, while better-sqlite3 needs `run` and throws on a
+     * statement that returns no rows.
+     *
+     * Returns nothing: this is for statements run to change data, not to read it.
+     *
+     * @param statement - Drizzle `sql` template to run
+     */
+    runStatement(statement: SQL): Promise<void>;
+    /**
+     * Run a Drizzle-built statement within the transaction and return its rows.
+     *
+     * @remarks
+     * The reading half of `runStatement`, for the same reason: a table the schema
+     * registry does not declare cannot be reached through the typed CRUD methods,
+     * which reject the name outright. Implemented per adapter because the drivers
+     * disagree about both the call and the result — node-postgres answers
+     * `{ rows }`, mysql2 a `[rows, fields]` tuple, and better-sqlite3 needs `all`.
+     *
+     * @param statement - Drizzle `sql` template to run
+     * @returns Rows the statement produced
+     */
+    queryStatement<T = Record<string, unknown>>(statement: SQL): Promise<T[]>;
+    /**
+     * Take an exclusive lock on a single row for the rest of this transaction.
+     *
+     * @remarks
+     * For read-modify-write sequences that must not interleave: without a lock
+     * another transaction can commit between the read and the write, leaving the
+     * caller's view of the prior state inconsistent with what its own write
+     * applied on top of.
+     *
+     * No-ops on dialects without row-level locking. SQLite is the case that
+     * matters and needs nothing — its transactions open with `BEGIN IMMEDIATE`,
+     * which already serializes writers.
+     *
+     * @param table - Table name
+     * @param id - Primary-key value of the row to lock
+     */
+    lockRow(table: string, id: SqlParam): Promise<void>;
     /**
      * Insert a single record.
      *
@@ -319,6 +406,31 @@ interface TransactionContext {
      * @returns Updated records (with RETURNING columns if specified)
      */
     update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    /**
+     * Update records and report how many rows the statement affected.
+     *
+     * @remarks
+     * The transactional half of the adapter's `updateCount`, and the only way to
+     * perform a fenced compare-and-set inside a transaction. `update` cannot
+     * answer this: without `returning` it discards the driver's count, and WITH
+     * `returning` on a dialect that lacks RETURNING it re-SELECTs using the same
+     * WHERE — so a conditional update whose own write falsifies its predicate
+     * reads back zero rows, and a write that landed reports as unmatched.
+     *
+     * 🔴 Inherits the adapter's MySQL caveat: MySQL counts CHANGED rows rather
+     * than matched ones, so a caller using this as a compare-and-set must write
+     * at least one column the update always moves — a state transition, a version
+     * bump, a timestamp of sufficient resolution. Postgres (`rowCount`) and
+     * SQLite (`changes`) count matched rows and do not need the precaution, which
+     * is exactly why it cannot be dropped: the dialect where the distinction
+     * exists is the one with no RETURNING to fall back on.
+     *
+     * @param table - Table name
+     * @param data - Column values to write
+     * @param where - Conditions the update must match
+     * @returns Number of rows the statement affected
+     */
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause): Promise<number>;
     /**
      * Delete records.
      *
@@ -365,6 +477,20 @@ interface TransactionContext {
      * @param name - Savepoint name
      */
     releaseSavepoint?(name: string): Promise<void>;
+    /**
+     * Return the Drizzle ORM instance bound to THIS transaction's connection.
+     *
+     * @remarks
+     * Runs Drizzle `sql` templates / fluent queries inside the caller's
+     * transaction (same client the delegated CRUD methods use), so services
+     * that drop to Drizzle raw SQL (e.g. junction-table writes) can participate
+     * in the transaction instead of running on the pooled connection. Required
+     * so callers never silently fall back to the pooled connection (which would
+     * run a write outside the transaction); every adapter must implement it.
+     * Generic return so callers narrow to the dialect Drizzle type they need
+     * without an `any` cast.
+     */
+    getDrizzle<T = unknown>(): T;
 }
 
 /**
@@ -619,4 +745,4 @@ interface MigrationStatus {
     pending: Migration[];
 }
 
-export type { DatabaseCapabilities as D, InsertOptions as I, JoinSpec as J, MigrationRecord as M, OrderBySpec as O, PoolStats as P, SelectOptions as S, TransactionContext as T, UpdateOptions as U, WhereClause as W, Migration as a, MigrationStatus as b, MigrationOptions as c, MigrationResult as d, TransactionOptions as e, DeleteOptions as f, UpsertOptions as g, TransactionIsolationLevel as h, WhereCondition as i, WhereOperator as j };
+export { type DeleteOptions as D, type InsertOptions as I, type JoinSpec as J, type MigrationRecord as M, type OrderBySpec as O, type PoolStats as P, type SelectOptions as S, type TransactionContext as T, type UpdateOptions as U, type WhereClause as W, type Migration as a, type MigrationStatus as b, type MigrationOptions as c, type MigrationResult as d, type UpsertOptions as e, type TransactionOptions as f, type DatabaseCapabilities as g, type TransactionIsolationLevel as h, WHERE_OPERATORS as i, type WhereCondition as j, type WhereOperator as k };

package/dist/{migration-BbO5meEV.d.cts → migration-DhMuYiIm.d.cts}

@@ -1,4 +1,5 @@
 import { a as SqlParam, S as SupportedDialect } from './core-CVO7WYDj.cjs';
+import { SQL } from 'drizzle-orm';
 
 /**
  * Query building type definitions for database-agnostic queries.
@@ -7,19 +8,42 @@ import { a as SqlParam, S as SupportedDialect } from './core-CVO7WYDj.cjs';
  */
 
 /**
- * Supported WHERE clause operators.
+ * Every WHERE clause operator this package DECLARES, as a value.
  *
  * @remarks
+ * Declared, not guaranteed executable. Membership here means a `WhereCondition`
+ * carrying the operator type-checks — it does NOT mean the adapter can run it.
+ * `OVERLAPS` is declared and unimplemented, and throws at build time, so a
+ * validator written against this list will admit input the query layer then
+ * rejects. Validate against it to catch a misspelled operator; do not read
+ * acceptance here as a capability.
+ *
  * - Standard comparison: =, !=, <, >, <=, >=
  * - Set operations: IN, NOT IN
  * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)
  * - NULL checks: IS NULL, IS NOT NULL
  * - Range: BETWEEN, NOT BETWEEN
- * - JSON/Array: CONTAINS, OVERLAPS
+ * - Substring: CONTAINS — a LITERAL match on a TEXT column; see below
+ * - Declared but NOT implemented: OVERLAPS, which throws
+ *
+ * This list is the source of truth and {@link WhereOperator} is derived from it,
+ * rather than the two being written out separately. A guard that has to enumerate
+ * the operators — a validator over caller input, or a test asserting the builder
+ * handles or refuses each one — can only do that from a runtime value, and a
+ * hand-kept copy of the union would agree with it on the day it was written and
+ * silently stop agreeing the next time a member is added.
+ *
+ * @public
+ */
+declare const WHERE_OPERATORS: readonly ["=", "!=", "<", ">", "<=", ">=", "IN", "NOT IN", "LIKE", "ILIKE", "IS NULL", "IS NOT NULL", "BETWEEN", "NOT BETWEEN", "CONTAINS", "OVERLAPS"];
+/**
+ * Every WHERE clause operator this package declares. Derived from
+ * {@link WHERE_OPERATORS}, and carrying the same caveat: a value of this type
+ * type-checks, which is not the same as the adapter being able to execute it.
  *
  * @public
  */
-type WhereOperator = "=" | "!=" | "<" | ">" | "<=" | ">=" | "IN" | "NOT IN" | "LIKE" | "ILIKE" | "IS NULL" | "IS NOT NULL" | "BETWEEN" | "NOT BETWEEN" | "CONTAINS" | "OVERLAPS";
+type WhereOperator = (typeof WHERE_OPERATORS)[number];
 /**
  * Individual WHERE condition.
  *
@@ -147,6 +171,17 @@ interface SelectOptions {
     having?: WhereClause;
     /** Return distinct rows only */
     distinct?: boolean;
+    /**
+     * Take a `FOR UPDATE` row lock on the selected rows for the rest of the
+     * transaction, and read the latest committed values rather than the
+     * transaction's snapshot. Use for read-modify-write sequences that must not
+     * interleave (e.g. re-reading a status under the lock the write will take).
+     *
+     * Requires a transaction executor. No-ops on SQLite, which has no `FOR UPDATE`
+     * and needs none — its transactions open with `BEGIN IMMEDIATE`, already
+     * serializing writers.
+     */
+    forUpdate?: boolean;
 }
 /**
  * Options for INSERT operations.
@@ -275,6 +310,58 @@ interface TransactionContext {
      * @returns Array of result rows
      */
     execute<T = unknown>(sql: string, params?: SqlParam[]): Promise<T[]>;
+    /**
+     * Run a Drizzle-built statement within the transaction, for its effect.
+     *
+     * @remarks
+     * The typed CRUD methods below resolve their table through the schema
+     * registry and reject any name it does not declare. That leaves no way to
+     * write to a table addressed under a name the ORM does not know — a table
+     * mid-rename, most of all — other than assembling SQL by hand, which also
+     * means hand-picking each driver's placeholder syntax.
+     *
+     * This accepts Drizzle's `sql` template instead, so identifier quoting and
+     * parameter binding are generated for the dialect in use. Implemented per
+     * adapter because the underlying call is not uniform: node-postgres and
+     * mysql2 expose `execute`, while better-sqlite3 needs `run` and throws on a
+     * statement that returns no rows.
+     *
+     * Returns nothing: this is for statements run to change data, not to read it.
+     *
+     * @param statement - Drizzle `sql` template to run
+     */
+    runStatement(statement: SQL): Promise<void>;
+    /**
+     * Run a Drizzle-built statement within the transaction and return its rows.
+     *
+     * @remarks
+     * The reading half of `runStatement`, for the same reason: a table the schema
+     * registry does not declare cannot be reached through the typed CRUD methods,
+     * which reject the name outright. Implemented per adapter because the drivers
+     * disagree about both the call and the result — node-postgres answers
+     * `{ rows }`, mysql2 a `[rows, fields]` tuple, and better-sqlite3 needs `all`.
+     *
+     * @param statement - Drizzle `sql` template to run
+     * @returns Rows the statement produced
+     */
+    queryStatement<T = Record<string, unknown>>(statement: SQL): Promise<T[]>;
+    /**
+     * Take an exclusive lock on a single row for the rest of this transaction.
+     *
+     * @remarks
+     * For read-modify-write sequences that must not interleave: without a lock
+     * another transaction can commit between the read and the write, leaving the
+     * caller's view of the prior state inconsistent with what its own write
+     * applied on top of.
+     *
+     * No-ops on dialects without row-level locking. SQLite is the case that
+     * matters and needs nothing — its transactions open with `BEGIN IMMEDIATE`,
+     * which already serializes writers.
+     *
+     * @param table - Table name
+     * @param id - Primary-key value of the row to lock
+     */
+    lockRow(table: string, id: SqlParam): Promise<void>;
     /**
      * Insert a single record.
      *
@@ -319,6 +406,31 @@ interface TransactionContext {
      * @returns Updated records (with RETURNING columns if specified)
      */
     update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereClause, options?: UpdateOptions): Promise<T[]>;
+    /**
+     * Update records and report how many rows the statement affected.
+     *
+     * @remarks
+     * The transactional half of the adapter's `updateCount`, and the only way to
+     * perform a fenced compare-and-set inside a transaction. `update` cannot
+     * answer this: without `returning` it discards the driver's count, and WITH
+     * `returning` on a dialect that lacks RETURNING it re-SELECTs using the same
+     * WHERE — so a conditional update whose own write falsifies its predicate
+     * reads back zero rows, and a write that landed reports as unmatched.
+     *
+     * 🔴 Inherits the adapter's MySQL caveat: MySQL counts CHANGED rows rather
+     * than matched ones, so a caller using this as a compare-and-set must write
+     * at least one column the update always moves — a state transition, a version
+     * bump, a timestamp of sufficient resolution. Postgres (`rowCount`) and
+     * SQLite (`changes`) count matched rows and do not need the precaution, which
+     * is exactly why it cannot be dropped: the dialect where the distinction
+     * exists is the one with no RETURNING to fall back on.
+     *
+     * @param table - Table name
+     * @param data - Column values to write
+     * @param where - Conditions the update must match
+     * @returns Number of rows the statement affected
+     */
+    updateCount(table: string, data: Record<string, unknown>, where: WhereClause): Promise<number>;
     /**
      * Delete records.
      *
@@ -365,6 +477,20 @@ interface TransactionContext {
      * @param name - Savepoint name
      */
     releaseSavepoint?(name: string): Promise<void>;
+    /**
+     * Return the Drizzle ORM instance bound to THIS transaction's connection.
+     *
+     * @remarks
+     * Runs Drizzle `sql` templates / fluent queries inside the caller's
+     * transaction (same client the delegated CRUD methods use), so services
+     * that drop to Drizzle raw SQL (e.g. junction-table writes) can participate
+     * in the transaction instead of running on the pooled connection. Required
+     * so callers never silently fall back to the pooled connection (which would
+     * run a write outside the transaction); every adapter must implement it.
+     * Generic return so callers narrow to the dialect Drizzle type they need
+     * without an `any` cast.
+     */
+    getDrizzle<T = unknown>(): T;
 }
 
 /**
@@ -619,4 +745,4 @@ interface MigrationStatus {
     pending: Migration[];
 }
 
-export type { DatabaseCapabilities as D, InsertOptions as I, JoinSpec as J, MigrationRecord as M, OrderBySpec as O, PoolStats as P, SelectOptions as S, TransactionContext as T, UpdateOptions as U, WhereClause as W, Migration as a, MigrationStatus as b, MigrationOptions as c, MigrationResult as d, TransactionOptions as e, DeleteOptions as f, UpsertOptions as g, TransactionIsolationLevel as h, WhereCondition as i, WhereOperator as j };
+export { type DeleteOptions as D, type InsertOptions as I, type JoinSpec as J, type MigrationRecord as M, type OrderBySpec as O, type PoolStats as P, type SelectOptions as S, type TransactionContext as T, type UpdateOptions as U, type WhereClause as W, type Migration as a, type MigrationStatus as b, type MigrationOptions as c, type MigrationResult as d, type UpsertOptions as e, type TransactionOptions as f, type DatabaseCapabilities as g, type TransactionIsolationLevel as h, WHERE_OPERATORS as i, type WhereCondition as j, type WhereOperator as k };

package/dist/migrations.d.cts

@@ -1,9 +1,10 @@
-import { D as DrizzleAdapter } from './adapter-nvlxFkF-.cjs';
-import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-BbO5meEV.cjs';
-export { d as MigrationResult } from './migration-BbO5meEV.cjs';
+import { D as DrizzleAdapter } from './adapter-BeMxQXZs.cjs';
+import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-DhMuYiIm.cjs';
+export { d as MigrationResult } from './migration-DhMuYiIm.cjs';
+import 'drizzle-orm';
 import './core-CVO7WYDj.cjs';
 import './schema-BDn8WfSL.cjs';
-import './error-um1d_3Uo.cjs';
+import './error-BrdknH2s.cjs';
 
 /**
  * Database migration utilities.

package/dist/migrations.d.ts

@@ -1,9 +1,10 @@
-import { D as DrizzleAdapter } from './adapter-BxJVtttb.js';
-import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-Qe70wDOC.js';
-export { d as MigrationResult } from './migration-Qe70wDOC.js';
+import { D as DrizzleAdapter } from './adapter-BRvxUZrS.js';
+import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-BnT96HFp.js';
+export { d as MigrationResult } from './migration-BnT96HFp.js';
+import 'drizzle-orm';
 import './core-CVO7WYDj.js';
 import './schema-BIQ0YQZ_.js';
-import './error-um1d_3Uo.js';
+import './error-BrdknH2s.js';
 
 /**
  * Database migration utilities.

package/dist/types/index.cjs

@@ -1,9 +1,45 @@
 'use strict';
 
+// src/types/query.ts
+var WHERE_OPERATORS = [
+  "=",
+  "!=",
+  "<",
+  ">",
+  "<=",
+  ">=",
+  "IN",
+  "NOT IN",
+  "LIKE",
+  "ILIKE",
+  "IS NULL",
+  "IS NOT NULL",
+  "BETWEEN",
+  "NOT BETWEEN",
+  // Substring match on a TEXT column, with the value taken literally. Despite the name it is
+  // not JSON containment, and it is not safe to point at a JSON column: the builder emits a
+  // bare `LIKE` with no cast, so on PostgreSQL a `json`/`jsonb` column has no matching operator
+  // and the statement ERRORS (`operator does not exist: jsonb ~~ text`). MySQL and SQLite
+  // coerce, and there it searches the serialized text — which hits a key name as readily as a
+  // value. Text columns only, and a search rather than a containment check.
+  "CONTAINS",
+  // Declared, never implemented — the builder throws `Unsupported operator: OVERLAPS`. Kept in
+  // the union because removing it would be a breaking change to a published type; the refusal
+  // is pinned by a test so implementing it has to come through here.
+  "OVERLAPS"
+];
+
 // src/types/error.ts
 function isDatabaseError(error) {
   return typeof error === "object" && error !== null && "kind" in error && typeof error.kind === "string";
 }
+var APPLICATION_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+function isApplicationError(error) {
+  if (error === null || typeof error !== "object" && typeof error !== "function") {
+    return false;
+  }
+  return error[APPLICATION_ERROR_BRAND] === true;
+}
 function createDatabaseError(options) {
   const error = new Error(options.message);
   error.name = "DatabaseError";
@@ -18,7 +54,9 @@ function createDatabaseError(options) {
   return error;
 }
 
+exports.WHERE_OPERATORS = WHERE_OPERATORS;
 exports.createDatabaseError = createDatabaseError;
+exports.isApplicationError = isApplicationError;
 exports.isDatabaseError = isDatabaseError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/types/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/error.ts"],"names":[],"mappings":";;;AAuFO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,MAAA,IAAU,KAAA,IACV,OAAQ,KAAA,CAAwB,IAAA,KAAS,QAAA;AAE7C;AA+CO,SAAS,oBACd,OAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA;AACvC,EAAA,KAAA,CAAM,IAAA,GAAO,eAAA;AACb,EAAA,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AAErB,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,aAAa,OAAA,CAAQ,UAAA;AACjE,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AACvD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AAEvD,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * Database error type definitions.\n *\n * @packageDocumentation\n */\n\n/**\n * Database error classification.\n *\n * @remarks\n * Categorizes database errors for consistent error handling across adapters.\n * Each adapter translates database-specific error codes to these kinds.\n *\n * @public\n */\nexport type DatabaseErrorKind =\n  | \"connection\" // Connection/network errors\n  | \"query\" // Syntax or execution errors\n  | \"constraint\" // Generic constraint violation\n  | \"unique_violation\" // Unique constraint violation\n  | \"foreign_key_violation\" // Foreign key constraint violation\n  | \"check_violation\" // Check constraint violation\n  | \"not_null_violation\" // NOT NULL constraint violation\n  | \"deadlock\" // Transaction deadlock\n  | \"timeout\" // Query or connection timeout\n  | \"serialization_failure\" // Serializable transaction conflict\n  | \"unsupported_version\" // F17: DB version below minimum or unparseable at connect\n  | \"unknown\"; // Unclassified error\n\n/**\n * Enhanced database error interface.\n *\n * @remarks\n * Extends the standard Error interface with database-specific context.\n * Adapters should throw errors implementing this interface for consistent\n * error handling.\n *\n * @example\n * ```typescript\n * try {\n *   await adapter.insert('users', { email: 'duplicate@example.com' });\n * } catch (error) {\n *   if (isDatabaseError(error) && error.kind === 'unique_violation') {\n *     console.log(`Duplicate ${error.column} in ${error.table}`);\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface DatabaseError extends Error {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Database-specific error code (e.g., \"23505\" for PostgreSQL unique violation) */\n  code?: string;\n\n  /** Constraint name that was violated (if applicable) */\n  constraint?: string;\n\n  /** Table name involved in the error */\n  table?: string;\n\n  /** Column name involved in the error */\n  column?: string;\n\n  /** Detailed error description from the database */\n  detail?: string;\n\n  /** Hint for resolving the error */\n  hint?: string;\n\n  /** Original error from the database driver */\n  cause?: Error;\n}\n\n/**\n * Type guard for DatabaseError.\n *\n * @remarks\n * Checks if an error is a DatabaseError with proper typing.\n *\n * @param error - Error to check\n * @returns True if error is a DatabaseError\n *\n * @public\n */\nexport function isDatabaseError(error: unknown): error is DatabaseError {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"kind\" in error &&\n    typeof (error as DatabaseError).kind === \"string\"\n  );\n}\n\n/**\n * Database error constructor options.\n *\n * @public\n */\nexport interface DatabaseErrorOptions {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Error message */\n  message: string;\n\n  /** Database-specific error code */\n  code?: string;\n\n  /** Constraint name */\n  constraint?: string;\n\n  /** Table name */\n  table?: string;\n\n  /** Column name */\n  column?: string;\n\n  /** Detailed description */\n  detail?: string;\n\n  /** Resolution hint */\n  hint?: string;\n\n  /** Original error */\n  cause?: Error;\n}\n\n/**\n * Create a DatabaseError instance.\n *\n * @remarks\n * Helper function to create properly structured DatabaseError objects.\n *\n * @param options - Error options\n * @returns DatabaseError instance\n *\n * @public\n */\nexport function createDatabaseError(\n  options: DatabaseErrorOptions\n): DatabaseError {\n  const error = new Error(options.message) as DatabaseError;\n  error.name = \"DatabaseError\";\n  error.kind = options.kind;\n\n  if (options.code !== undefined) error.code = options.code;\n  if (options.constraint !== undefined) error.constraint = options.constraint;\n  if (options.table !== undefined) error.table = options.table;\n  if (options.column !== undefined) error.column = options.column;\n  if (options.detail !== undefined) error.detail = options.detail;\n  if (options.hint !== undefined) error.hint = options.hint;\n  if (options.cause !== undefined) error.cause = options.cause;\n\n  return error;\n}\n"]}
+{"version":3,"sources":["../../src/types/query.ts","../../src/types/error.ts"],"names":[],"mappings":";;;AAoCO,IAAM,eAAA,GAAkB;AAAA,EAC7B,GAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,IAAA;AAAA,EACA,IAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,aAAA;AAAA,EACA,SAAA;AAAA,EACA,aAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA;AAAA;AAAA;AAAA;AAAA,EAIA;AACF;;;ACyBO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,MAAA,IAAU,KAAA,IACV,OAAQ,KAAA,CAAwB,IAAA,KAAS,QAAA;AAE7C;AAYA,IAAM,uBAAA,GAAyC,MAAA,CAAO,GAAA,CAAI,oBAAoB,CAAA;AAkBvE,SAAS,mBAAmB,KAAA,EAAyB;AAC1D,EAAA,IACE,UAAU,IAAA,IACT,OAAO,UAAU,QAAA,IAAY,OAAO,UAAU,UAAA,EAC/C;AACA,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAQ,KAAA,CAAkC,uBAAuB,CAAA,KAAM,IAAA;AACzE;AA+CO,SAAS,oBACd,OAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA;AACvC,EAAA,KAAA,CAAM,IAAA,GAAO,eAAA;AACb,EAAA,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AAErB,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,aAAa,OAAA,CAAQ,UAAA;AACjE,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AACvD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AAEvD,EAAA,OAAO,KAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * Query building type definitions for database-agnostic queries.\n *\n * @packageDocumentation\n */\n\nimport type { SqlParam } from \"./core\";\n\n/**\n * Every WHERE clause operator this package DECLARES, as a value.\n *\n * @remarks\n * Declared, not guaranteed executable. Membership here means a `WhereCondition`\n * carrying the operator type-checks — it does NOT mean the adapter can run it.\n * `OVERLAPS` is declared and unimplemented, and throws at build time, so a\n * validator written against this list will admit input the query layer then\n * rejects. Validate against it to catch a misspelled operator; do not read\n * acceptance here as a capability.\n *\n * - Standard comparison: =, !=, <, >, <=, >=\n * - Set operations: IN, NOT IN\n * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)\n * - NULL checks: IS NULL, IS NOT NULL\n * - Range: BETWEEN, NOT BETWEEN\n * - Substring: CONTAINS — a LITERAL match on a TEXT column; see below\n * - Declared but NOT implemented: OVERLAPS, which throws\n *\n * This list is the source of truth and {@link WhereOperator} is derived from it,\n * rather than the two being written out separately. A guard that has to enumerate\n * the operators — a validator over caller input, or a test asserting the builder\n * handles or refuses each one — can only do that from a runtime value, and a\n * hand-kept copy of the union would agree with it on the day it was written and\n * silently stop agreeing the next time a member is added.\n *\n * @public\n */\nexport const WHERE_OPERATORS = [\n  \"=\",\n  \"!=\",\n  \"<\",\n  \">\",\n  \"<=\",\n  \">=\",\n  \"IN\",\n  \"NOT IN\",\n  \"LIKE\",\n  \"ILIKE\",\n  \"IS NULL\",\n  \"IS NOT NULL\",\n  \"BETWEEN\",\n  \"NOT BETWEEN\",\n  // Substring match on a TEXT column, with the value taken literally. Despite the name it is\n  // not JSON containment, and it is not safe to point at a JSON column: the builder emits a\n  // bare `LIKE` with no cast, so on PostgreSQL a `json`/`jsonb` column has no matching operator\n  // and the statement ERRORS (`operator does not exist: jsonb ~~ text`). MySQL and SQLite\n  // coerce, and there it searches the serialized text — which hits a key name as readily as a\n  // value. Text columns only, and a search rather than a containment check.\n  \"CONTAINS\",\n  // Declared, never implemented — the builder throws `Unsupported operator: OVERLAPS`. Kept in\n  // the union because removing it would be a breaking change to a published type; the refusal\n  // is pinned by a test so implementing it has to come through here.\n  \"OVERLAPS\",\n] as const;\n\n/**\n * Every WHERE clause operator this package declares. Derived from\n * {@link WHERE_OPERATORS}, and carrying the same caveat: a value of this type\n * type-checks, which is not the same as the adapter being able to execute it.\n *\n * @public\n */\nexport type WhereOperator = (typeof WHERE_OPERATORS)[number];\n\n/**\n * Individual WHERE condition.\n *\n * @remarks\n * Represents a single condition in a WHERE clause. For IS NULL and IS NOT NULL\n * operators, the value field is optional.\n *\n * @public\n */\nexport interface WhereCondition {\n  /** Column name to filter on */\n  column: string;\n\n  /** Comparison operator */\n  op: WhereOperator;\n\n  /** Value(s) to compare against (optional for IS NULL/IS NOT NULL) */\n  value?: SqlParam | SqlParam[];\n\n  /** Second value for BETWEEN operator */\n  valueTo?: SqlParam;\n}\n\n/**\n * Complex WHERE clause with logical operators.\n *\n * @remarks\n * Supports nested conditions with AND, OR, and NOT logical operators.\n * Can be recursively nested for complex queries.\n *\n * @example\n * ```typescript\n * const where: WhereClause = {\n *   and: [\n *     { column: \"status\", op: \"=\", value: \"published\" },\n *     {\n *       or: [\n *         { column: \"author\", op: \"=\", value: \"john\" },\n *         { column: \"author\", op: \"=\", value: \"jane\" }\n *       ]\n *     }\n *   ]\n * };\n * ```\n *\n * @public\n */\nexport interface WhereClause {\n  /** All conditions must be true (AND) */\n  and?: (WhereCondition | WhereClause)[];\n\n  /** At least one condition must be true (OR) */\n  or?: (WhereCondition | WhereClause)[];\n\n  /** Negate a condition (NOT) */\n  not?: WhereCondition | WhereClause;\n}\n\n/**\n * ORDER BY specification for query results.\n *\n * @remarks\n * Controls the sorting of query results. NULL handling varies by database\n * but can be explicitly controlled with the nulls field.\n *\n * @public\n */\nexport interface OrderBySpec {\n  /** Column name to sort by */\n  column: string;\n\n  /** Sort direction (default: asc) */\n  direction?: \"asc\" | \"desc\";\n\n  /** NULL value ordering (database-specific defaults vary) */\n  nulls?: \"first\" | \"last\";\n}\n\n/**\n * JOIN specification for table joins.\n *\n * @remarks\n * Supports different types of JOINs. Note that complex joins may require\n * dialect-specific handling.\n *\n * @public\n */\nexport interface JoinSpec {\n  /** Type of join */\n  type: \"inner\" | \"left\" | \"right\" | \"full\";\n\n  /** Table name to join */\n  table: string;\n\n  /** Join condition */\n  on: {\n    /** Column from the left table */\n    leftColumn: string;\n    /** Column from the right table */\n    rightColumn: string;\n  };\n\n  /** Optional alias for the joined table */\n  alias?: string;\n}\n","/**\n * Database error type definitions.\n *\n * @packageDocumentation\n */\n\n/**\n * Database error classification.\n *\n * @remarks\n * Categorizes database errors for consistent error handling across adapters.\n * Each adapter translates database-specific error codes to these kinds.\n *\n * @public\n */\nexport type DatabaseErrorKind =\n  | \"connection\" // Connection/network errors\n  | \"query\" // Syntax or execution errors\n  | \"constraint\" // Generic constraint violation\n  | \"unique_violation\" // Unique constraint violation\n  | \"foreign_key_violation\" // Foreign key constraint violation\n  | \"check_violation\" // Check constraint violation\n  | \"not_null_violation\" // NOT NULL constraint violation\n  | \"deadlock\" // Transaction deadlock\n  | \"timeout\" // Query or connection timeout\n  | \"serialization_failure\" // Serializable transaction conflict\n  | \"unsupported_version\" // F17: DB version below minimum or unparseable at connect\n  | \"unknown\"; // Unclassified error\n\n/**\n * Enhanced database error interface.\n *\n * @remarks\n * Extends the standard Error interface with database-specific context.\n * Adapters should throw errors implementing this interface for consistent\n * error handling.\n *\n * @example\n * ```typescript\n * try {\n *   await adapter.insert('users', { email: 'duplicate@example.com' });\n * } catch (error) {\n *   if (isDatabaseError(error) && error.kind === 'unique_violation') {\n *     console.log(`Duplicate ${error.column} in ${error.table}`);\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface DatabaseError extends Error {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Database-specific error code (e.g., \"23505\" for PostgreSQL unique violation) */\n  code?: string;\n\n  /** Constraint name that was violated (if applicable) */\n  constraint?: string;\n\n  /** Table name involved in the error */\n  table?: string;\n\n  /** Column name involved in the error */\n  column?: string;\n\n  /** Detailed error description from the database */\n  detail?: string;\n\n  /** Hint for resolving the error */\n  hint?: string;\n\n  /** Original error from the database driver */\n  cause?: Error;\n}\n\n/**\n * Type guard for DatabaseError.\n *\n * @remarks\n * Checks if an error is a DatabaseError with proper typing.\n *\n * @param error - Error to check\n * @returns True if error is a DatabaseError\n *\n * @public\n */\nexport function isDatabaseError(error: unknown): error is DatabaseError {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"kind\" in error &&\n    typeof (error as DatabaseError).kind === \"string\"\n  );\n}\n\n/**\n * The brand every Nextly application error carries.\n *\n * Read through the global symbol registry rather than imported, because the\n * adapters must not depend on the package that defines the error: `Symbol.for`\n * resolves to the same symbol in every module instance, which is why the brand\n * exists in that form to begin with.\n *\n * @internal\n */\nconst APPLICATION_ERROR_BRAND: unique symbol = Symbol.for(\"nextly/NextlyError\");\n\n/**\n * Whether an error is the application's verdict rather than the database's\n * failure.\n *\n * Work running inside a transaction may throw to roll the write back — a\n * refused value, a permission denial — and such an error is not something the\n * driver produced. Classifying it as a database error replaces its code and its\n * payload with a generic one, so a caller that asked for a refusal is handed an\n * unexplained failure instead, and per-field validation detail is lost on the\n * way out.\n *\n * @param error - Error to check\n * @returns True if the error was raised by application code\n *\n * @public\n */\nexport function isApplicationError(error: unknown): boolean {\n  if (\n    error === null ||\n    (typeof error !== \"object\" && typeof error !== \"function\")\n  ) {\n    return false;\n  }\n  return (error as Record<symbol, unknown>)[APPLICATION_ERROR_BRAND] === true;\n}\n\n/**\n * Database error constructor options.\n *\n * @public\n */\nexport interface DatabaseErrorOptions {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Error message */\n  message: string;\n\n  /** Database-specific error code */\n  code?: string;\n\n  /** Constraint name */\n  constraint?: string;\n\n  /** Table name */\n  table?: string;\n\n  /** Column name */\n  column?: string;\n\n  /** Detailed description */\n  detail?: string;\n\n  /** Resolution hint */\n  hint?: string;\n\n  /** Original error */\n  cause?: Error;\n}\n\n/**\n * Create a DatabaseError instance.\n *\n * @remarks\n * Helper function to create properly structured DatabaseError objects.\n *\n * @param options - Error options\n * @returns DatabaseError instance\n *\n * @public\n */\nexport function createDatabaseError(\n  options: DatabaseErrorOptions\n): DatabaseError {\n  const error = new Error(options.message) as DatabaseError;\n  error.name = \"DatabaseError\";\n  error.kind = options.kind;\n\n  if (options.code !== undefined) error.code = options.code;\n  if (options.constraint !== undefined) error.constraint = options.constraint;\n  if (options.table !== undefined) error.table = options.table;\n  if (options.column !== undefined) error.column = options.column;\n  if (options.detail !== undefined) error.detail = options.detail;\n  if (options.hint !== undefined) error.hint = options.hint;\n  if (options.cause !== undefined) error.cause = options.cause;\n\n  return error;\n}\n"]}

package/dist/types/index.d.cts

@@ -1,8 +1,9 @@
 import { a as SqlParam } from '../core-CVO7WYDj.cjs';
 export { J as JsonArray, b as JsonObject, c as JsonValue, S as SupportedDialect, T as TableResolver } from '../core-CVO7WYDj.cjs';
-export { D as DatabaseCapabilities, f as DeleteOptions, I as InsertOptions, J as JoinSpec, a as Migration, c as MigrationOptions, M as MigrationRecord, d as MigrationResult, b as MigrationStatus, O as OrderBySpec, P as PoolStats, S as SelectOptions, T as TransactionContext, h as TransactionIsolationLevel, e as TransactionOptions, U as UpdateOptions, g as UpsertOptions, W as WhereClause, i as WhereCondition, j as WhereOperator } from '../migration-BbO5meEV.cjs';
+export { g as DatabaseCapabilities, D as DeleteOptions, I as InsertOptions, J as JoinSpec, a as Migration, c as MigrationOptions, M as MigrationRecord, d as MigrationResult, b as MigrationStatus, O as OrderBySpec, P as PoolStats, S as SelectOptions, T as TransactionContext, h as TransactionIsolationLevel, f as TransactionOptions, U as UpdateOptions, e as UpsertOptions, i as WHERE_OPERATORS, W as WhereClause, j as WhereCondition, k as WhereOperator } from '../migration-DhMuYiIm.cjs';
 export { A as AlterTableOperation, a as AlterTableOptions, b as ColumnDefinition, C as CreateTableOptions, D as DropTableOptions, I as IndexDefinition, c as TableConstraint, T as TableDefinition } from '../schema-BDn8WfSL.cjs';
-export { a as DatabaseError, D as DatabaseErrorKind, b as DatabaseErrorOptions, c as createDatabaseError, i as isDatabaseError } from '../error-um1d_3Uo.cjs';
+export { a as DatabaseError, D as DatabaseErrorKind, b as DatabaseErrorOptions, c as createDatabaseError, i as isApplicationError, d as isDatabaseError } from '../error-BrdknH2s.cjs';
+import 'drizzle-orm';
 
 /**
  * Database adapter configuration type definitions.

package/dist/types/index.d.ts

@@ -1,8 +1,9 @@
 import { a as SqlParam } from '../core-CVO7WYDj.js';
 export { J as JsonArray, b as JsonObject, c as JsonValue, S as SupportedDialect, T as TableResolver } from '../core-CVO7WYDj.js';
-export { D as DatabaseCapabilities, f as DeleteOptions, I as InsertOptions, J as JoinSpec, a as Migration, c as MigrationOptions, M as MigrationRecord, d as MigrationResult, b as MigrationStatus, O as OrderBySpec, P as PoolStats, S as SelectOptions, T as TransactionContext, h as TransactionIsolationLevel, e as TransactionOptions, U as UpdateOptions, g as UpsertOptions, W as WhereClause, i as WhereCondition, j as WhereOperator } from '../migration-Qe70wDOC.js';
+export { g as DatabaseCapabilities, D as DeleteOptions, I as InsertOptions, J as JoinSpec, a as Migration, c as MigrationOptions, M as MigrationRecord, d as MigrationResult, b as MigrationStatus, O as OrderBySpec, P as PoolStats, S as SelectOptions, T as TransactionContext, h as TransactionIsolationLevel, f as TransactionOptions, U as UpdateOptions, e as UpsertOptions, i as WHERE_OPERATORS, W as WhereClause, j as WhereCondition, k as WhereOperator } from '../migration-BnT96HFp.js';
 export { A as AlterTableOperation, a as AlterTableOptions, b as ColumnDefinition, C as CreateTableOptions, D as DropTableOptions, I as IndexDefinition, c as TableConstraint, T as TableDefinition } from '../schema-BIQ0YQZ_.js';
-export { a as DatabaseError, D as DatabaseErrorKind, b as DatabaseErrorOptions, c as createDatabaseError, i as isDatabaseError } from '../error-um1d_3Uo.js';
+export { a as DatabaseError, D as DatabaseErrorKind, b as DatabaseErrorOptions, c as createDatabaseError, i as isApplicationError, d as isDatabaseError } from '../error-BrdknH2s.js';
+import 'drizzle-orm';
 
 /**
  * Database adapter configuration type definitions.

package/dist/types/index.mjs

@@ -1,7 +1,43 @@
+// src/types/query.ts
+var WHERE_OPERATORS = [
+  "=",
+  "!=",
+  "<",
+  ">",
+  "<=",
+  ">=",
+  "IN",
+  "NOT IN",
+  "LIKE",
+  "ILIKE",
+  "IS NULL",
+  "IS NOT NULL",
+  "BETWEEN",
+  "NOT BETWEEN",
+  // Substring match on a TEXT column, with the value taken literally. Despite the name it is
+  // not JSON containment, and it is not safe to point at a JSON column: the builder emits a
+  // bare `LIKE` with no cast, so on PostgreSQL a `json`/`jsonb` column has no matching operator
+  // and the statement ERRORS (`operator does not exist: jsonb ~~ text`). MySQL and SQLite
+  // coerce, and there it searches the serialized text — which hits a key name as readily as a
+  // value. Text columns only, and a search rather than a containment check.
+  "CONTAINS",
+  // Declared, never implemented — the builder throws `Unsupported operator: OVERLAPS`. Kept in
+  // the union because removing it would be a breaking change to a published type; the refusal
+  // is pinned by a test so implementing it has to come through here.
+  "OVERLAPS"
+];
+
 // src/types/error.ts
 function isDatabaseError(error) {
   return typeof error === "object" && error !== null && "kind" in error && typeof error.kind === "string";
 }
+var APPLICATION_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+function isApplicationError(error) {
+  if (error === null || typeof error !== "object" && typeof error !== "function") {
+    return false;
+  }
+  return error[APPLICATION_ERROR_BRAND] === true;
+}
 function createDatabaseError(options) {
   const error = new Error(options.message);
   error.name = "DatabaseError";
@@ -16,6 +52,6 @@ function createDatabaseError(options) {
   return error;
 }
 
-export { createDatabaseError, isDatabaseError };
+export { WHERE_OPERATORS, createDatabaseError, isApplicationError, isDatabaseError };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/types/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/types/error.ts"],"names":[],"mappings":";AAuFO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,MAAA,IAAU,KAAA,IACV,OAAQ,KAAA,CAAwB,IAAA,KAAS,QAAA;AAE7C;AA+CO,SAAS,oBACd,OAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA;AACvC,EAAA,KAAA,CAAM,IAAA,GAAO,eAAA;AACb,EAAA,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AAErB,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,aAAa,OAAA,CAAQ,UAAA;AACjE,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AACvD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AAEvD,EAAA,OAAO,KAAA;AACT","file":"index.mjs","sourcesContent":["/**\n * Database error type definitions.\n *\n * @packageDocumentation\n */\n\n/**\n * Database error classification.\n *\n * @remarks\n * Categorizes database errors for consistent error handling across adapters.\n * Each adapter translates database-specific error codes to these kinds.\n *\n * @public\n */\nexport type DatabaseErrorKind =\n  | \"connection\" // Connection/network errors\n  | \"query\" // Syntax or execution errors\n  | \"constraint\" // Generic constraint violation\n  | \"unique_violation\" // Unique constraint violation\n  | \"foreign_key_violation\" // Foreign key constraint violation\n  | \"check_violation\" // Check constraint violation\n  | \"not_null_violation\" // NOT NULL constraint violation\n  | \"deadlock\" // Transaction deadlock\n  | \"timeout\" // Query or connection timeout\n  | \"serialization_failure\" // Serializable transaction conflict\n  | \"unsupported_version\" // F17: DB version below minimum or unparseable at connect\n  | \"unknown\"; // Unclassified error\n\n/**\n * Enhanced database error interface.\n *\n * @remarks\n * Extends the standard Error interface with database-specific context.\n * Adapters should throw errors implementing this interface for consistent\n * error handling.\n *\n * @example\n * ```typescript\n * try {\n *   await adapter.insert('users', { email: 'duplicate@example.com' });\n * } catch (error) {\n *   if (isDatabaseError(error) && error.kind === 'unique_violation') {\n *     console.log(`Duplicate ${error.column} in ${error.table}`);\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface DatabaseError extends Error {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Database-specific error code (e.g., \"23505\" for PostgreSQL unique violation) */\n  code?: string;\n\n  /** Constraint name that was violated (if applicable) */\n  constraint?: string;\n\n  /** Table name involved in the error */\n  table?: string;\n\n  /** Column name involved in the error */\n  column?: string;\n\n  /** Detailed error description from the database */\n  detail?: string;\n\n  /** Hint for resolving the error */\n  hint?: string;\n\n  /** Original error from the database driver */\n  cause?: Error;\n}\n\n/**\n * Type guard for DatabaseError.\n *\n * @remarks\n * Checks if an error is a DatabaseError with proper typing.\n *\n * @param error - Error to check\n * @returns True if error is a DatabaseError\n *\n * @public\n */\nexport function isDatabaseError(error: unknown): error is DatabaseError {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"kind\" in error &&\n    typeof (error as DatabaseError).kind === \"string\"\n  );\n}\n\n/**\n * Database error constructor options.\n *\n * @public\n */\nexport interface DatabaseErrorOptions {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Error message */\n  message: string;\n\n  /** Database-specific error code */\n  code?: string;\n\n  /** Constraint name */\n  constraint?: string;\n\n  /** Table name */\n  table?: string;\n\n  /** Column name */\n  column?: string;\n\n  /** Detailed description */\n  detail?: string;\n\n  /** Resolution hint */\n  hint?: string;\n\n  /** Original error */\n  cause?: Error;\n}\n\n/**\n * Create a DatabaseError instance.\n *\n * @remarks\n * Helper function to create properly structured DatabaseError objects.\n *\n * @param options - Error options\n * @returns DatabaseError instance\n *\n * @public\n */\nexport function createDatabaseError(\n  options: DatabaseErrorOptions\n): DatabaseError {\n  const error = new Error(options.message) as DatabaseError;\n  error.name = \"DatabaseError\";\n  error.kind = options.kind;\n\n  if (options.code !== undefined) error.code = options.code;\n  if (options.constraint !== undefined) error.constraint = options.constraint;\n  if (options.table !== undefined) error.table = options.table;\n  if (options.column !== undefined) error.column = options.column;\n  if (options.detail !== undefined) error.detail = options.detail;\n  if (options.hint !== undefined) error.hint = options.hint;\n  if (options.cause !== undefined) error.cause = options.cause;\n\n  return error;\n}\n"]}
+{"version":3,"sources":["../../src/types/query.ts","../../src/types/error.ts"],"names":[],"mappings":";AAoCO,IAAM,eAAA,GAAkB;AAAA,EAC7B,GAAA;AAAA,EACA,IAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,IAAA;AAAA,EACA,IAAA;AAAA,EACA,IAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EACA,OAAA;AAAA,EACA,SAAA;AAAA,EACA,aAAA;AAAA,EACA,SAAA;AAAA,EACA,aAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,UAAA;AAAA;AAAA;AAAA;AAAA,EAIA;AACF;;;ACyBO,SAAS,gBAAgB,KAAA,EAAwC;AACtE,EAAA,OACE,OAAO,UAAU,QAAA,IACjB,KAAA,KAAU,QACV,MAAA,IAAU,KAAA,IACV,OAAQ,KAAA,CAAwB,IAAA,KAAS,QAAA;AAE7C;AAYA,IAAM,uBAAA,GAAyC,MAAA,CAAO,GAAA,CAAI,oBAAoB,CAAA;AAkBvE,SAAS,mBAAmB,KAAA,EAAyB;AAC1D,EAAA,IACE,UAAU,IAAA,IACT,OAAO,UAAU,QAAA,IAAY,OAAO,UAAU,UAAA,EAC/C;AACA,IAAA,OAAO,KAAA;AAAA,EACT;AACA,EAAA,OAAQ,KAAA,CAAkC,uBAAuB,CAAA,KAAM,IAAA;AACzE;AA+CO,SAAS,oBACd,OAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,IAAI,KAAA,CAAM,OAAA,CAAQ,OAAO,CAAA;AACvC,EAAA,KAAA,CAAM,IAAA,GAAO,eAAA;AACb,EAAA,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AAErB,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,UAAA,KAAe,MAAA,EAAW,KAAA,CAAM,aAAa,OAAA,CAAQ,UAAA;AACjE,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AACvD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,MAAA,KAAW,MAAA,EAAW,KAAA,CAAM,SAAS,OAAA,CAAQ,MAAA;AACzD,EAAA,IAAI,OAAA,CAAQ,IAAA,KAAS,MAAA,EAAW,KAAA,CAAM,OAAO,OAAA,CAAQ,IAAA;AACrD,EAAA,IAAI,OAAA,CAAQ,KAAA,KAAU,MAAA,EAAW,KAAA,CAAM,QAAQ,OAAA,CAAQ,KAAA;AAEvD,EAAA,OAAO,KAAA;AACT","file":"index.mjs","sourcesContent":["/**\n * Query building type definitions for database-agnostic queries.\n *\n * @packageDocumentation\n */\n\nimport type { SqlParam } from \"./core\";\n\n/**\n * Every WHERE clause operator this package DECLARES, as a value.\n *\n * @remarks\n * Declared, not guaranteed executable. Membership here means a `WhereCondition`\n * carrying the operator type-checks — it does NOT mean the adapter can run it.\n * `OVERLAPS` is declared and unimplemented, and throws at build time, so a\n * validator written against this list will admit input the query layer then\n * rejects. Validate against it to catch a misspelled operator; do not read\n * acceptance here as a capability.\n *\n * - Standard comparison: =, !=, <, >, <=, >=\n * - Set operations: IN, NOT IN\n * - Pattern matching: LIKE, ILIKE (case-insensitive, PostgreSQL/emulated)\n * - NULL checks: IS NULL, IS NOT NULL\n * - Range: BETWEEN, NOT BETWEEN\n * - Substring: CONTAINS — a LITERAL match on a TEXT column; see below\n * - Declared but NOT implemented: OVERLAPS, which throws\n *\n * This list is the source of truth and {@link WhereOperator} is derived from it,\n * rather than the two being written out separately. A guard that has to enumerate\n * the operators — a validator over caller input, or a test asserting the builder\n * handles or refuses each one — can only do that from a runtime value, and a\n * hand-kept copy of the union would agree with it on the day it was written and\n * silently stop agreeing the next time a member is added.\n *\n * @public\n */\nexport const WHERE_OPERATORS = [\n  \"=\",\n  \"!=\",\n  \"<\",\n  \">\",\n  \"<=\",\n  \">=\",\n  \"IN\",\n  \"NOT IN\",\n  \"LIKE\",\n  \"ILIKE\",\n  \"IS NULL\",\n  \"IS NOT NULL\",\n  \"BETWEEN\",\n  \"NOT BETWEEN\",\n  // Substring match on a TEXT column, with the value taken literally. Despite the name it is\n  // not JSON containment, and it is not safe to point at a JSON column: the builder emits a\n  // bare `LIKE` with no cast, so on PostgreSQL a `json`/`jsonb` column has no matching operator\n  // and the statement ERRORS (`operator does not exist: jsonb ~~ text`). MySQL and SQLite\n  // coerce, and there it searches the serialized text — which hits a key name as readily as a\n  // value. Text columns only, and a search rather than a containment check.\n  \"CONTAINS\",\n  // Declared, never implemented — the builder throws `Unsupported operator: OVERLAPS`. Kept in\n  // the union because removing it would be a breaking change to a published type; the refusal\n  // is pinned by a test so implementing it has to come through here.\n  \"OVERLAPS\",\n] as const;\n\n/**\n * Every WHERE clause operator this package declares. Derived from\n * {@link WHERE_OPERATORS}, and carrying the same caveat: a value of this type\n * type-checks, which is not the same as the adapter being able to execute it.\n *\n * @public\n */\nexport type WhereOperator = (typeof WHERE_OPERATORS)[number];\n\n/**\n * Individual WHERE condition.\n *\n * @remarks\n * Represents a single condition in a WHERE clause. For IS NULL and IS NOT NULL\n * operators, the value field is optional.\n *\n * @public\n */\nexport interface WhereCondition {\n  /** Column name to filter on */\n  column: string;\n\n  /** Comparison operator */\n  op: WhereOperator;\n\n  /** Value(s) to compare against (optional for IS NULL/IS NOT NULL) */\n  value?: SqlParam | SqlParam[];\n\n  /** Second value for BETWEEN operator */\n  valueTo?: SqlParam;\n}\n\n/**\n * Complex WHERE clause with logical operators.\n *\n * @remarks\n * Supports nested conditions with AND, OR, and NOT logical operators.\n * Can be recursively nested for complex queries.\n *\n * @example\n * ```typescript\n * const where: WhereClause = {\n *   and: [\n *     { column: \"status\", op: \"=\", value: \"published\" },\n *     {\n *       or: [\n *         { column: \"author\", op: \"=\", value: \"john\" },\n *         { column: \"author\", op: \"=\", value: \"jane\" }\n *       ]\n *     }\n *   ]\n * };\n * ```\n *\n * @public\n */\nexport interface WhereClause {\n  /** All conditions must be true (AND) */\n  and?: (WhereCondition | WhereClause)[];\n\n  /** At least one condition must be true (OR) */\n  or?: (WhereCondition | WhereClause)[];\n\n  /** Negate a condition (NOT) */\n  not?: WhereCondition | WhereClause;\n}\n\n/**\n * ORDER BY specification for query results.\n *\n * @remarks\n * Controls the sorting of query results. NULL handling varies by database\n * but can be explicitly controlled with the nulls field.\n *\n * @public\n */\nexport interface OrderBySpec {\n  /** Column name to sort by */\n  column: string;\n\n  /** Sort direction (default: asc) */\n  direction?: \"asc\" | \"desc\";\n\n  /** NULL value ordering (database-specific defaults vary) */\n  nulls?: \"first\" | \"last\";\n}\n\n/**\n * JOIN specification for table joins.\n *\n * @remarks\n * Supports different types of JOINs. Note that complex joins may require\n * dialect-specific handling.\n *\n * @public\n */\nexport interface JoinSpec {\n  /** Type of join */\n  type: \"inner\" | \"left\" | \"right\" | \"full\";\n\n  /** Table name to join */\n  table: string;\n\n  /** Join condition */\n  on: {\n    /** Column from the left table */\n    leftColumn: string;\n    /** Column from the right table */\n    rightColumn: string;\n  };\n\n  /** Optional alias for the joined table */\n  alias?: string;\n}\n","/**\n * Database error type definitions.\n *\n * @packageDocumentation\n */\n\n/**\n * Database error classification.\n *\n * @remarks\n * Categorizes database errors for consistent error handling across adapters.\n * Each adapter translates database-specific error codes to these kinds.\n *\n * @public\n */\nexport type DatabaseErrorKind =\n  | \"connection\" // Connection/network errors\n  | \"query\" // Syntax or execution errors\n  | \"constraint\" // Generic constraint violation\n  | \"unique_violation\" // Unique constraint violation\n  | \"foreign_key_violation\" // Foreign key constraint violation\n  | \"check_violation\" // Check constraint violation\n  | \"not_null_violation\" // NOT NULL constraint violation\n  | \"deadlock\" // Transaction deadlock\n  | \"timeout\" // Query or connection timeout\n  | \"serialization_failure\" // Serializable transaction conflict\n  | \"unsupported_version\" // F17: DB version below minimum or unparseable at connect\n  | \"unknown\"; // Unclassified error\n\n/**\n * Enhanced database error interface.\n *\n * @remarks\n * Extends the standard Error interface with database-specific context.\n * Adapters should throw errors implementing this interface for consistent\n * error handling.\n *\n * @example\n * ```typescript\n * try {\n *   await adapter.insert('users', { email: 'duplicate@example.com' });\n * } catch (error) {\n *   if (isDatabaseError(error) && error.kind === 'unique_violation') {\n *     console.log(`Duplicate ${error.column} in ${error.table}`);\n *   }\n * }\n * ```\n *\n * @public\n */\nexport interface DatabaseError extends Error {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Database-specific error code (e.g., \"23505\" for PostgreSQL unique violation) */\n  code?: string;\n\n  /** Constraint name that was violated (if applicable) */\n  constraint?: string;\n\n  /** Table name involved in the error */\n  table?: string;\n\n  /** Column name involved in the error */\n  column?: string;\n\n  /** Detailed error description from the database */\n  detail?: string;\n\n  /** Hint for resolving the error */\n  hint?: string;\n\n  /** Original error from the database driver */\n  cause?: Error;\n}\n\n/**\n * Type guard for DatabaseError.\n *\n * @remarks\n * Checks if an error is a DatabaseError with proper typing.\n *\n * @param error - Error to check\n * @returns True if error is a DatabaseError\n *\n * @public\n */\nexport function isDatabaseError(error: unknown): error is DatabaseError {\n  return (\n    typeof error === \"object\" &&\n    error !== null &&\n    \"kind\" in error &&\n    typeof (error as DatabaseError).kind === \"string\"\n  );\n}\n\n/**\n * The brand every Nextly application error carries.\n *\n * Read through the global symbol registry rather than imported, because the\n * adapters must not depend on the package that defines the error: `Symbol.for`\n * resolves to the same symbol in every module instance, which is why the brand\n * exists in that form to begin with.\n *\n * @internal\n */\nconst APPLICATION_ERROR_BRAND: unique symbol = Symbol.for(\"nextly/NextlyError\");\n\n/**\n * Whether an error is the application's verdict rather than the database's\n * failure.\n *\n * Work running inside a transaction may throw to roll the write back — a\n * refused value, a permission denial — and such an error is not something the\n * driver produced. Classifying it as a database error replaces its code and its\n * payload with a generic one, so a caller that asked for a refusal is handed an\n * unexplained failure instead, and per-field validation detail is lost on the\n * way out.\n *\n * @param error - Error to check\n * @returns True if the error was raised by application code\n *\n * @public\n */\nexport function isApplicationError(error: unknown): boolean {\n  if (\n    error === null ||\n    (typeof error !== \"object\" && typeof error !== \"function\")\n  ) {\n    return false;\n  }\n  return (error as Record<symbol, unknown>)[APPLICATION_ERROR_BRAND] === true;\n}\n\n/**\n * Database error constructor options.\n *\n * @public\n */\nexport interface DatabaseErrorOptions {\n  /** Error classification */\n  kind: DatabaseErrorKind;\n\n  /** Error message */\n  message: string;\n\n  /** Database-specific error code */\n  code?: string;\n\n  /** Constraint name */\n  constraint?: string;\n\n  /** Table name */\n  table?: string;\n\n  /** Column name */\n  column?: string;\n\n  /** Detailed description */\n  detail?: string;\n\n  /** Resolution hint */\n  hint?: string;\n\n  /** Original error */\n  cause?: Error;\n}\n\n/**\n * Create a DatabaseError instance.\n *\n * @remarks\n * Helper function to create properly structured DatabaseError objects.\n *\n * @param options - Error options\n * @returns DatabaseError instance\n *\n * @public\n */\nexport function createDatabaseError(\n  options: DatabaseErrorOptions\n): DatabaseError {\n  const error = new Error(options.message) as DatabaseError;\n  error.name = \"DatabaseError\";\n  error.kind = options.kind;\n\n  if (options.code !== undefined) error.code = options.code;\n  if (options.constraint !== undefined) error.constraint = options.constraint;\n  if (options.table !== undefined) error.table = options.table;\n  if (options.column !== undefined) error.column = options.column;\n  if (options.detail !== undefined) error.detail = options.detail;\n  if (options.hint !== undefined) error.hint = options.hint;\n  if (options.cause !== undefined) error.cause = options.cause;\n\n  return error;\n}\n"]}

package/dist/version-check.d.cts

@@ -1,5 +1,5 @@
 import { S as SupportedDialect } from './core-CVO7WYDj.cjs';
-import { a as DatabaseError } from './error-um1d_3Uo.cjs';
+import { a as DatabaseError } from './error-BrdknH2s.cjs';
 
 declare const NEXTLY_MIN_DB_VERSIONS: {
     readonly postgresql: {