@nextlyhq/adapter-drizzle 0.0.2-alpha.67 → 0.0.2-alpha.69

package/dist/types-CNyA1oIm.cjs

@@ -0,0 +1,185 @@
+// src/types/query.ts
+/**
+* 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
+* - 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
+*/
+const WHERE_OPERATORS = [
+	"=",
+	"!=",
+	"<",
+	">",
+	"<=",
+	">=",
+	"IN",
+	"NOT IN",
+	"LIKE",
+	"ILIKE",
+	"IS NULL",
+	"IS NOT NULL",
+	"BETWEEN",
+	"NOT BETWEEN",
+	"CONTAINS",
+	"ICONTAINS",
+	"OVERLAPS"
+];
+// src/types/error.ts
+/**
+* Type guard for DatabaseError.
+*
+* @remarks
+* Checks if an error is a DatabaseError with proper typing.
+*
+* @param error - Error to check
+* @returns True if error is a DatabaseError
+*
+* @public
+*/
+function isDatabaseError(error) {
+	return typeof error === "object" && error !== null && "kind" in error && typeof error.kind === "string";
+}
+/**
+* The brand every Nextly application error carries.
+*
+* Read through the global symbol registry rather than imported, because the
+* adapters must not depend on the package that defines the error: `Symbol.for`
+* resolves to the same symbol in every module instance, which is why the brand
+* exists in that form to begin with.
+*
+* @internal
+*/
+const APPLICATION_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+/**
+* Whether an error is the application's verdict rather than the database's
+* failure.
+*
+* Work running inside a transaction may throw to roll the write back — a
+* refused value, a permission denial — and such an error is not something the
+* driver produced. Classifying it as a database error replaces its code and its
+* payload with a generic one, so a caller that asked for a refusal is handed an
+* unexplained failure instead, and per-field validation detail is lost on the
+* way out.
+*
+* @param error - Error to check
+* @returns True if the error was raised by application code
+*
+* @public
+*/
+function isApplicationError(error) {
+	if (error === null || typeof error !== "object" && typeof error !== "function") return false;
+	return error[APPLICATION_ERROR_BRAND] === true;
+}
+/**
+* Create a DatabaseError instance.
+*
+* @remarks
+* Helper function to create properly structured DatabaseError objects.
+*
+* @param options - Error options
+* @returns DatabaseError instance
+*
+* @public
+*/
+function createDatabaseError(options) {
+	const error = new Error(options.message);
+	error.name = "DatabaseError";
+	error.kind = options.kind;
+	if (options.code !== void 0) error.code = options.code;
+	if (options.constraint !== void 0) error.constraint = options.constraint;
+	if (options.table !== void 0) error.table = options.table;
+	if (options.column !== void 0) error.column = options.column;
+	if (options.detail !== void 0) error.detail = options.detail;
+	if (options.hint !== void 0) error.hint = options.hint;
+	if (options.cause !== void 0) error.cause = options.cause;
+	return error;
+}
+/**
+* The code an adapter gives the error it raises when a request has waited
+* longer than `pool.connectionTimeoutMs` for a database connection.
+*
+* A code of the adapters' own rather than the driver's wording, because the
+* drivers disagree: pg-pool raises a plain `Error` with no code, mysql2 has no
+* such wait to time out, and better-sqlite3 has no pool. Core reads this one
+* code to answer with its retryable "database busy" error.
+*
+* @public
+*/
+const POOL_WAIT_TIMEOUT_CODE = "NEXTLY_POOL_WAIT_TIMEOUT";
+/**
+* The error for a request that waited `boundMs` for a database connection and
+* was given none.
+*
+* @param boundMs - The bound it waited, `pool.connectionTimeoutMs`
+* @param cause - The driver's own error, when the driver raised one
+*
+* @public
+*/
+function poolWaitTimeoutError(boundMs, cause) {
+	return createDatabaseError({
+		kind: "timeout",
+		code: POOL_WAIT_TIMEOUT_CODE,
+		message: `Waited ${boundMs} ms for a database connection, and none was free`,
+		cause
+	});
+}
+Object.defineProperty(exports, "POOL_WAIT_TIMEOUT_CODE", {
+	enumerable: true,
+	get: function() {
+		return POOL_WAIT_TIMEOUT_CODE;
+	}
+});
+Object.defineProperty(exports, "WHERE_OPERATORS", {
+	enumerable: true,
+	get: function() {
+		return WHERE_OPERATORS;
+	}
+});
+Object.defineProperty(exports, "createDatabaseError", {
+	enumerable: true,
+	get: function() {
+		return createDatabaseError;
+	}
+});
+Object.defineProperty(exports, "isApplicationError", {
+	enumerable: true,
+	get: function() {
+		return isApplicationError;
+	}
+});
+Object.defineProperty(exports, "isDatabaseError", {
+	enumerable: true,
+	get: function() {
+		return isDatabaseError;
+	}
+});
+Object.defineProperty(exports, "poolWaitTimeoutError", {
+	enumerable: true,
+	get: function() {
+		return poolWaitTimeoutError;
+	}
+});
+
+//# sourceMappingURL=types-CNyA1oIm.cjs.map

package/dist/types-CNyA1oIm.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CNyA1oIm.cjs","names":[],"sources":["../src/types/query.ts","../src/types/error.ts"],"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  // CONTAINS without regard to case: a substring match on a TEXT column with the value taken\n  // literally (`%` and `_` are characters to find, not wildcards), ignoring case on every\n  // dialect even where the column's collation is case-sensitive. Which letters fold is the\n  // database's `lower()` under the column's collation: the collation's Unicode version on\n  // MySQL; non-ASCII too under a linguistic PostgreSQL collation; ASCII letters only on\n  // SQLite and under PostgreSQL's `C` or `POSIX`.\n  \"ICONTAINS\",\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\n/**\n * The code an adapter gives the error it raises when a request has waited\n * longer than `pool.connectionTimeoutMs` for a database connection.\n *\n * A code of the adapters' own rather than the driver's wording, because the\n * drivers disagree: pg-pool raises a plain `Error` with no code, mysql2 has no\n * such wait to time out, and better-sqlite3 has no pool. Core reads this one\n * code to answer with its retryable \"database busy\" error.\n *\n * @public\n */\nexport const POOL_WAIT_TIMEOUT_CODE = \"NEXTLY_POOL_WAIT_TIMEOUT\";\n\n/**\n * The error for a request that waited `boundMs` for a database connection and\n * was given none.\n *\n * @param boundMs - The bound it waited, `pool.connectionTimeoutMs`\n * @param cause - The driver's own error, when the driver raised one\n *\n * @public\n */\nexport function poolWaitTimeoutError(\n  boundMs: number,\n  cause?: Error\n): DatabaseError {\n  return createDatabaseError({\n    kind: \"timeout\",\n    code: POOL_WAIT_TIMEOUT_CODE,\n    message: `Waited ${boundMs} ms for a database connection, and none was free`,\n    cause,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAOA;CAOA;CAIA;AACF;;;;;;;;;;;;;ACkBA,SAAgB,gBAAgB,OAAwC;CACtE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAQ,MAAwB,SAAS;AAE7C;;;;;;;;;;;AAYA,MAAM,0BAAyC,OAAO,IAAI,oBAAoB;;;;;;;;;;;;;;;;;AAkB9E,SAAgB,mBAAmB,OAAyB;CAC1D,IACE,UAAU,QACT,OAAO,UAAU,YAAY,OAAO,UAAU,YAE/C,OAAO;CAET,OAAQ,MAAkC,6BAA6B;AACzE;;;;;;;;;;;;AA+CA,SAAgB,oBACd,SACe;CACf,MAAM,QAAQ,IAAI,MAAM,QAAQ,OAAO;CACvC,MAAM,OAAO;CACb,MAAM,OAAO,QAAQ;CAErB,IAAI,QAAQ,SAAS,KAAA,GAAW,MAAM,OAAO,QAAQ;CACrD,IAAI,QAAQ,eAAe,KAAA,GAAW,MAAM,aAAa,QAAQ;CACjE,IAAI,QAAQ,UAAU,KAAA,GAAW,MAAM,QAAQ,QAAQ;CACvD,IAAI,QAAQ,WAAW,KAAA,GAAW,MAAM,SAAS,QAAQ;CACzD,IAAI,QAAQ,WAAW,KAAA,GAAW,MAAM,SAAS,QAAQ;CACzD,IAAI,QAAQ,SAAS,KAAA,GAAW,MAAM,OAAO,QAAQ;CACrD,IAAI,QAAQ,UAAU,KAAA,GAAW,MAAM,QAAQ,QAAQ;CAEvD,OAAO;AACT;;;;;;;;;;;;AAaA,MAAa,yBAAyB;;;;;;;;;;AAWtC,SAAgB,qBACd,SACA,OACe;CACf,OAAO,oBAAoB;EACzB,MAAM;EACN,MAAM;EACN,SAAS,UAAU,QAAQ;EAC3B;CACF,CAAC;AACH"}

package/dist/types-CaF_5jNk.mjs

@@ -0,0 +1,150 @@
+// src/types/query.ts
+/**
+* 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
+* - 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
+*/
+const WHERE_OPERATORS = [
+	"=",
+	"!=",
+	"<",
+	">",
+	"<=",
+	">=",
+	"IN",
+	"NOT IN",
+	"LIKE",
+	"ILIKE",
+	"IS NULL",
+	"IS NOT NULL",
+	"BETWEEN",
+	"NOT BETWEEN",
+	"CONTAINS",
+	"ICONTAINS",
+	"OVERLAPS"
+];
+// src/types/error.ts
+/**
+* Type guard for DatabaseError.
+*
+* @remarks
+* Checks if an error is a DatabaseError with proper typing.
+*
+* @param error - Error to check
+* @returns True if error is a DatabaseError
+*
+* @public
+*/
+function isDatabaseError(error) {
+	return typeof error === "object" && error !== null && "kind" in error && typeof error.kind === "string";
+}
+/**
+* The brand every Nextly application error carries.
+*
+* Read through the global symbol registry rather than imported, because the
+* adapters must not depend on the package that defines the error: `Symbol.for`
+* resolves to the same symbol in every module instance, which is why the brand
+* exists in that form to begin with.
+*
+* @internal
+*/
+const APPLICATION_ERROR_BRAND = Symbol.for("nextly/NextlyError");
+/**
+* Whether an error is the application's verdict rather than the database's
+* failure.
+*
+* Work running inside a transaction may throw to roll the write back — a
+* refused value, a permission denial — and such an error is not something the
+* driver produced. Classifying it as a database error replaces its code and its
+* payload with a generic one, so a caller that asked for a refusal is handed an
+* unexplained failure instead, and per-field validation detail is lost on the
+* way out.
+*
+* @param error - Error to check
+* @returns True if the error was raised by application code
+*
+* @public
+*/
+function isApplicationError(error) {
+	if (error === null || typeof error !== "object" && typeof error !== "function") return false;
+	return error[APPLICATION_ERROR_BRAND] === true;
+}
+/**
+* Create a DatabaseError instance.
+*
+* @remarks
+* Helper function to create properly structured DatabaseError objects.
+*
+* @param options - Error options
+* @returns DatabaseError instance
+*
+* @public
+*/
+function createDatabaseError(options) {
+	const error = new Error(options.message);
+	error.name = "DatabaseError";
+	error.kind = options.kind;
+	if (options.code !== void 0) error.code = options.code;
+	if (options.constraint !== void 0) error.constraint = options.constraint;
+	if (options.table !== void 0) error.table = options.table;
+	if (options.column !== void 0) error.column = options.column;
+	if (options.detail !== void 0) error.detail = options.detail;
+	if (options.hint !== void 0) error.hint = options.hint;
+	if (options.cause !== void 0) error.cause = options.cause;
+	return error;
+}
+/**
+* The code an adapter gives the error it raises when a request has waited
+* longer than `pool.connectionTimeoutMs` for a database connection.
+*
+* A code of the adapters' own rather than the driver's wording, because the
+* drivers disagree: pg-pool raises a plain `Error` with no code, mysql2 has no
+* such wait to time out, and better-sqlite3 has no pool. Core reads this one
+* code to answer with its retryable "database busy" error.
+*
+* @public
+*/
+const POOL_WAIT_TIMEOUT_CODE = "NEXTLY_POOL_WAIT_TIMEOUT";
+/**
+* The error for a request that waited `boundMs` for a database connection and
+* was given none.
+*
+* @param boundMs - The bound it waited, `pool.connectionTimeoutMs`
+* @param cause - The driver's own error, when the driver raised one
+*
+* @public
+*/
+function poolWaitTimeoutError(boundMs, cause) {
+	return createDatabaseError({
+		kind: "timeout",
+		code: POOL_WAIT_TIMEOUT_CODE,
+		message: `Waited ${boundMs} ms for a database connection, and none was free`,
+		cause
+	});
+}
+export { poolWaitTimeoutError as a, isDatabaseError as i, createDatabaseError as n, WHERE_OPERATORS as o, isApplicationError as r, POOL_WAIT_TIMEOUT_CODE as t };
+
+//# sourceMappingURL=types-CaF_5jNk.mjs.map

package/dist/types-CaF_5jNk.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"types-CaF_5jNk.mjs","names":[],"sources":["../src/types/query.ts","../src/types/error.ts"],"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  // CONTAINS without regard to case: a substring match on a TEXT column with the value taken\n  // literally (`%` and `_` are characters to find, not wildcards), ignoring case on every\n  // dialect even where the column's collation is case-sensitive. Which letters fold is the\n  // database's `lower()` under the column's collation: the collation's Unicode version on\n  // MySQL; non-ASCII too under a linguistic PostgreSQL collation; ASCII letters only on\n  // SQLite and under PostgreSQL's `C` or `POSIX`.\n  \"ICONTAINS\",\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\n/**\n * The code an adapter gives the error it raises when a request has waited\n * longer than `pool.connectionTimeoutMs` for a database connection.\n *\n * A code of the adapters' own rather than the driver's wording, because the\n * drivers disagree: pg-pool raises a plain `Error` with no code, mysql2 has no\n * such wait to time out, and better-sqlite3 has no pool. Core reads this one\n * code to answer with its retryable \"database busy\" error.\n *\n * @public\n */\nexport const POOL_WAIT_TIMEOUT_CODE = \"NEXTLY_POOL_WAIT_TIMEOUT\";\n\n/**\n * The error for a request that waited `boundMs` for a database connection and\n * was given none.\n *\n * @param boundMs - The bound it waited, `pool.connectionTimeoutMs`\n * @param cause - The driver's own error, when the driver raised one\n *\n * @public\n */\nexport function poolWaitTimeoutError(\n  boundMs: number,\n  cause?: Error\n): DatabaseError {\n  return createDatabaseError({\n    kind: \"timeout\",\n    code: POOL_WAIT_TIMEOUT_CODE,\n    message: `Waited ${boundMs} ms for a database connection, and none was free`,\n    cause,\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoCA,MAAa,kBAAkB;CAC7B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAOA;CAOA;CAIA;AACF;;;;;;;;;;;;;ACkBA,SAAgB,gBAAgB,OAAwC;CACtE,OACE,OAAO,UAAU,YACjB,UAAU,QACV,UAAU,SACV,OAAQ,MAAwB,SAAS;AAE7C;;;;;;;;;;;AAYA,MAAM,0BAAyC,OAAO,IAAI,oBAAoB;;;;;;;;;;;;;;;;;AAkB9E,SAAgB,mBAAmB,OAAyB;CAC1D,IACE,UAAU,QACT,OAAO,UAAU,YAAY,OAAO,UAAU,YAE/C,OAAO;CAET,OAAQ,MAAkC,6BAA6B;AACzE;;;;;;;;;;;;AA+CA,SAAgB,oBACd,SACe;CACf,MAAM,QAAQ,IAAI,MAAM,QAAQ,OAAO;CACvC,MAAM,OAAO;CACb,MAAM,OAAO,QAAQ;CAErB,IAAI,QAAQ,SAAS,KAAA,GAAW,MAAM,OAAO,QAAQ;CACrD,IAAI,QAAQ,eAAe,KAAA,GAAW,MAAM,aAAa,QAAQ;CACjE,IAAI,QAAQ,UAAU,KAAA,GAAW,MAAM,QAAQ,QAAQ;CACvD,IAAI,QAAQ,WAAW,KAAA,GAAW,MAAM,SAAS,QAAQ;CACzD,IAAI,QAAQ,WAAW,KAAA,GAAW,MAAM,SAAS,QAAQ;CACzD,IAAI,QAAQ,SAAS,KAAA,GAAW,MAAM,OAAO,QAAQ;CACrD,IAAI,QAAQ,UAAU,KAAA,GAAW,MAAM,QAAQ,QAAQ;CAEvD,OAAO;AACT;;;;;;;;;;;;AAaA,MAAa,yBAAyB;;;;;;;;;;AAWtC,SAAgB,qBACd,SACA,OACe;CACf,OAAO,oBAAoB;EACzB,MAAM;EACN,MAAM;EACN,SAAS,UAAU,QAAQ;EAC3B;CACF,CAAC;AACH"}