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

package/dist/{migration-BUc56kip.d.cts → migration-B6AmjCQ1.d.cts}

@@ -8,19 +8,42 @@ import { SQL } from 'drizzle-orm';
  */
 
 /**
- * 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.
  *
@@ -129,6 +152,30 @@ interface JoinSpec {
  *
  * @public
  */
+/**
+ * What a COUNT asks for.
+ *
+ * 🔴 `distinctOn` is a column LIST rather than a boolean, and the difference is
+ * the whole reason this option exists: counting rows and counting the things
+ * those rows are about are different questions whenever a thing can own more
+ * than one row. A document holding a pending edit in three languages is one
+ * document and three version rows.
+ */
+interface CountOptions {
+    /** Filter conditions, the same vocabulary `select` takes. */
+    where?: WhereClause;
+    /**
+     * Count DISTINCT combinations of these columns instead of rows.
+     *
+     * Compiled as `COUNT(*)` over a `SELECT DISTINCT` subquery rather than as
+     * `COUNT(DISTINCT a, b)`, because the latter is not portable: MySQL accepts
+     * it, PostgreSQL requires a row constructor, and SQLite rejects it outright
+     * with "wrong number of arguments to function count()". The subquery is the
+     * one form all three engines agree on, and it is what this compiles to on
+     * every dialect so the number cannot differ by engine.
+     */
+    distinctOn?: string[];
+}
 interface SelectOptions {
     /** Specific columns to select (default: all columns) */
     columns?: string[];
@@ -383,6 +430,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.
      *
@@ -697,4 +769,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 CountOptions as C, 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-Bj84e15B.d.ts → migration-R06fsTrz.d.ts}

@@ -8,19 +8,42 @@ import { SQL } from 'drizzle-orm';
  */
 
 /**
- * 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.
  *
@@ -129,6 +152,30 @@ interface JoinSpec {
  *
  * @public
  */
+/**
+ * What a COUNT asks for.
+ *
+ * 🔴 `distinctOn` is a column LIST rather than a boolean, and the difference is
+ * the whole reason this option exists: counting rows and counting the things
+ * those rows are about are different questions whenever a thing can own more
+ * than one row. A document holding a pending edit in three languages is one
+ * document and three version rows.
+ */
+interface CountOptions {
+    /** Filter conditions, the same vocabulary `select` takes. */
+    where?: WhereClause;
+    /**
+     * Count DISTINCT combinations of these columns instead of rows.
+     *
+     * Compiled as `COUNT(*)` over a `SELECT DISTINCT` subquery rather than as
+     * `COUNT(DISTINCT a, b)`, because the latter is not portable: MySQL accepts
+     * it, PostgreSQL requires a row constructor, and SQLite rejects it outright
+     * with "wrong number of arguments to function count()". The subquery is the
+     * one form all three engines agree on, and it is what this compiles to on
+     * every dialect so the number cannot differ by engine.
+     */
+    distinctOn?: string[];
+}
 interface SelectOptions {
     /** Specific columns to select (default: all columns) */
     columns?: string[];
@@ -383,6 +430,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.
      *
@@ -697,4 +769,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 CountOptions as C, 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,6 +1,6 @@
-import { D as DrizzleAdapter } from './adapter-BG7MnOUw.cjs';
-import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-BUc56kip.cjs';
-export { d as MigrationResult } from './migration-BUc56kip.cjs';
+import { D as DrizzleAdapter } from './adapter-C6ENLDau.cjs';
+import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-B6AmjCQ1.cjs';
+export { d as MigrationResult } from './migration-B6AmjCQ1.cjs';
 import 'drizzle-orm';
 import './core-CVO7WYDj.cjs';
 import './schema-BDn8WfSL.cjs';

package/dist/migrations.d.ts

@@ -1,6 +1,6 @@
-import { D as DrizzleAdapter } from './adapter-DjPoLjBK.js';
-import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-Bj84e15B.js';
-export { d as MigrationResult } from './migration-Bj84e15B.js';
+import { D as DrizzleAdapter } from './adapter-D4GM1VAZ.js';
+import { M as MigrationRecord, a as Migration, b as MigrationStatus, c as MigrationOptions } from './migration-R06fsTrz.js';
+export { d as MigrationResult } from './migration-R06fsTrz.js';
 import 'drizzle-orm';
 import './core-CVO7WYDj.js';
 import './schema-BIQ0YQZ_.js';

package/dist/types/index.cjs

@@ -1,5 +1,34 @@
 '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";
@@ -25,6 +54,7 @@ function createDatabaseError(options) {
   return error;
 }
 
+exports.WHERE_OPERATORS = WHERE_OPERATORS;
 exports.createDatabaseError = createDatabaseError;
 exports.isApplicationError = isApplicationError;
 exports.isDatabaseError = isDatabaseError;

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;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 * 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"]}
+{"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,6 +1,6 @@
 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-BUc56kip.cjs';
+export { C as CountOptions, 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-B6AmjCQ1.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 isApplicationError, d as isDatabaseError } from '../error-BrdknH2s.cjs';
 import 'drizzle-orm';

package/dist/types/index.d.ts

@@ -1,6 +1,6 @@
 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-Bj84e15B.js';
+export { C as CountOptions, 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-R06fsTrz.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 isApplicationError, d as isDatabaseError } from '../error-BrdknH2s.js';
 import 'drizzle-orm';

package/dist/types/index.mjs

@@ -1,3 +1,32 @@
+// 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";
@@ -23,6 +52,6 @@ function createDatabaseError(options) {
   return error;
 }
 
-export { createDatabaseError, isApplicationError, 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;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 * 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"]}
+{"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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextlyhq/adapter-drizzle",
-  "version": "0.0.2-alpha.60",
+  "version": "0.0.2-alpha.64",
   "description": "Shared Drizzle ORM adapter logic for Nextly database adapters",
   "license": "MIT",
   "type": "module",
@@ -52,8 +52,8 @@
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^4.1.0",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.60",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.60"
+    "@nextlyhq/eslint-config": "0.0.2-alpha.64",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.64"
   },
   "repository": {
     "type": "git",