effect-qb 0.15.0 → 0.17.0

package/src/sqlite/errors/catalog.ts

@@ -0,0 +1,103 @@
+export const sqliteErrorCategories = {
+  sqlite: "sqlite"
+} as const
+
+export type SqliteErrorCategory = keyof typeof sqliteErrorCategories
+
+type SqliteErrorDescriptorShape<Symbol extends string = string> = {
+  readonly category: "sqlite"
+  readonly number: `${number}`
+  readonly symbol: Symbol
+  readonly tag: `@sqlite/${Lowercase<Symbol>}`
+  readonly messageTemplate: string
+}
+
+const descriptor = <Symbol extends string>(
+  number: `${number}`,
+  symbol: Symbol,
+  messageTemplate: string
+): SqliteErrorDescriptorShape<Symbol> => ({
+  category: "sqlite",
+  number,
+  symbol,
+  tag: `@sqlite/${symbol.toLowerCase()}` as `@sqlite/${Lowercase<Symbol>}`,
+  messageTemplate
+})
+
+export const sqliteErrorCatalogBySymbol = {
+  SQLITE_ERROR: descriptor("1", "SQLITE_ERROR", "SQL error or missing database"),
+  SQLITE_INTERNAL: descriptor("2", "SQLITE_INTERNAL", "Internal SQLite logic error"),
+  SQLITE_PERM: descriptor("3", "SQLITE_PERM", "Access permission denied"),
+  SQLITE_ABORT: descriptor("4", "SQLITE_ABORT", "Callback routine requested an abort"),
+  SQLITE_BUSY: descriptor("5", "SQLITE_BUSY", "Database file is locked"),
+  SQLITE_LOCKED: descriptor("6", "SQLITE_LOCKED", "Database table is locked"),
+  SQLITE_NOMEM: descriptor("7", "SQLITE_NOMEM", "Out of memory"),
+  SQLITE_READONLY: descriptor("8", "SQLITE_READONLY", "Attempt to write a readonly database"),
+  SQLITE_INTERRUPT: descriptor("9", "SQLITE_INTERRUPT", "Operation terminated by sqlite3_interrupt"),
+  SQLITE_IOERR: descriptor("10", "SQLITE_IOERR", "Disk I/O error"),
+  SQLITE_CORRUPT: descriptor("11", "SQLITE_CORRUPT", "Database disk image is malformed"),
+  SQLITE_NOTFOUND: descriptor("12", "SQLITE_NOTFOUND", "Unknown opcode"),
+  SQLITE_FULL: descriptor("13", "SQLITE_FULL", "Insertion failed because database is full"),
+  SQLITE_CANTOPEN: descriptor("14", "SQLITE_CANTOPEN", "Unable to open the database file"),
+  SQLITE_PROTOCOL: descriptor("15", "SQLITE_PROTOCOL", "Database lock protocol error"),
+  SQLITE_EMPTY: descriptor("16", "SQLITE_EMPTY", "Database is empty"),
+  SQLITE_SCHEMA: descriptor("17", "SQLITE_SCHEMA", "Database schema changed"),
+  SQLITE_TOOBIG: descriptor("18", "SQLITE_TOOBIG", "String or blob exceeds size limit"),
+  SQLITE_CONSTRAINT: descriptor("19", "SQLITE_CONSTRAINT", "Constraint violation"),
+  SQLITE_MISMATCH: descriptor("20", "SQLITE_MISMATCH", "Data type mismatch"),
+  SQLITE_MISUSE: descriptor("21", "SQLITE_MISUSE", "Library used incorrectly"),
+  SQLITE_NOLFS: descriptor("22", "SQLITE_NOLFS", "Uses OS features not supported on host"),
+  SQLITE_AUTH: descriptor("23", "SQLITE_AUTH", "Authorization denied"),
+  SQLITE_FORMAT: descriptor("24", "SQLITE_FORMAT", "Auxiliary database format error"),
+  SQLITE_RANGE: descriptor("25", "SQLITE_RANGE", "Bind parameter index out of range"),
+  SQLITE_NOTADB: descriptor("26", "SQLITE_NOTADB", "File is not a database"),
+  SQLITE_NOTICE: descriptor("27", "SQLITE_NOTICE", "Notifications from sqlite3_log"),
+  SQLITE_WARNING: descriptor("28", "SQLITE_WARNING", "Warnings from sqlite3_log"),
+  SQLITE_ROW: descriptor("100", "SQLITE_ROW", "sqlite3_step has another row ready"),
+  SQLITE_DONE: descriptor("101", "SQLITE_DONE", "sqlite3_step has finished executing"),
+  SQLITE_BUSY_RECOVERY: descriptor("261", "SQLITE_BUSY_RECOVERY", "Database is busy recovering"),
+  SQLITE_BUSY_SNAPSHOT: descriptor("517", "SQLITE_BUSY_SNAPSHOT", "Database snapshot is busy"),
+  SQLITE_BUSY_TIMEOUT: descriptor("773", "SQLITE_BUSY_TIMEOUT", "Blocking POSIX advisory lock timed out"),
+  SQLITE_CONSTRAINT_CHECK: descriptor("275", "SQLITE_CONSTRAINT_CHECK", "CHECK constraint failed"),
+  SQLITE_CONSTRAINT_FOREIGNKEY: descriptor("787", "SQLITE_CONSTRAINT_FOREIGNKEY", "FOREIGN KEY constraint failed"),
+  SQLITE_CONSTRAINT_NOTNULL: descriptor("1299", "SQLITE_CONSTRAINT_NOTNULL", "NOT NULL constraint failed"),
+  SQLITE_CONSTRAINT_PRIMARYKEY: descriptor("1555", "SQLITE_CONSTRAINT_PRIMARYKEY", "PRIMARY KEY constraint failed"),
+  SQLITE_CONSTRAINT_UNIQUE: descriptor("2067", "SQLITE_CONSTRAINT_UNIQUE", "UNIQUE constraint failed")
+} as const
+
+export type SqliteErrorSymbol = keyof typeof sqliteErrorCatalogBySymbol
+
+export type SqliteErrorDescriptor = (typeof sqliteErrorCatalogBySymbol)[SqliteErrorSymbol]
+
+export type SqliteErrorNumber = SqliteErrorDescriptor["number"]
+
+export type SqliteErrorTag = SqliteErrorDescriptor["tag"]
+
+const sqliteErrorDescriptors = Object.values(sqliteErrorCatalogBySymbol)
+
+export const sqliteErrorCatalogByNumber = sqliteErrorDescriptors.reduce(
+  (acc, entry) => ({
+    ...acc,
+    [entry.number]: [...(acc[entry.number as SqliteErrorNumber] ?? []), entry]
+  }),
+  {} as Record<SqliteErrorNumber, readonly SqliteErrorDescriptor[]>
+)
+
+export const isSqliteErrorSymbol = (value: string): value is SqliteErrorSymbol =>
+  value in sqliteErrorCatalogBySymbol
+
+export const isSqliteErrorNumber = (value: string): value is SqliteErrorNumber =>
+  value in sqliteErrorCatalogByNumber
+
+export const getSqliteErrorDescriptor = (
+  symbol: SqliteErrorSymbol
+): SqliteErrorDescriptor => sqliteErrorCatalogBySymbol[symbol]
+
+export const findSqliteErrorDescriptorsByNumber = (
+  number: SqliteErrorNumber
+): readonly SqliteErrorDescriptor[] => sqliteErrorCatalogByNumber[number] ?? []
+
+export const findSqliteErrorDescriptorsByNumberLoose = (
+  number: string
+): readonly SqliteErrorDescriptor[] | undefined =>
+  isSqliteErrorNumber(number) ? sqliteErrorCatalogByNumber[number] : undefined

package/src/sqlite/errors/fields.ts

@@ -0,0 +1,19 @@
+/** Common SQLite driver error fields surfaced by the normalizer when present. */
+export interface SqliteErrorFields {
+  readonly code?: string
+  readonly errno?: number
+  readonly sqlState?: string
+  readonly sqlMessage?: string
+  readonly fatal?: boolean
+  readonly sql?: string
+  readonly syscall?: string
+  readonly address?: string
+  readonly port?: number
+  readonly hostname?: string
+}
+
+/** Rendered SQL context attached to normalized SQLite execution failures. */
+export interface SqliteQueryContext {
+  readonly sql: string
+  readonly params: readonly unknown[]
+}

package/src/sqlite/errors/index.ts

@@ -0,0 +1,19 @@
+export * from "./catalog.js"
+export * from "./fields.js"
+export * from "./normalize.js"
+export * from "./requirements.js"
+export * from "./types.js"
+
+export {
+  findSqliteErrorDescriptorsByNumber as findSqliteErrorDescriptorsByNumber,
+  getSqliteErrorDescriptor as getSqliteErrorDescriptor,
+  isSqliteErrorNumber as isSqliteErrorNumber,
+  isSqliteErrorSymbol as isSqliteErrorSymbol
+} from "./catalog.js"
+
+export {
+  hasNumber as hasErrorNumber,
+  hasSymbol as hasErrorSymbol,
+  isSqliteErrorLike as isSqliteErrorLike,
+  normalizeSqliteDriverError as normalizeSqliteDriverError
+} from "./normalize.js"

package/src/sqlite/errors/normalize.ts

@@ -0,0 +1,229 @@
+import type * as Renderer from "../../internal/renderer.js"
+import {
+  findSqliteErrorDescriptorsByNumberLoose,
+  getSqliteErrorDescriptor,
+  isSqliteErrorNumber,
+  isSqliteErrorSymbol,
+  type SqliteErrorDescriptor,
+  type SqliteErrorNumber,
+  type SqliteErrorSymbol,
+} from "./catalog.js"
+import type {
+  SqliteErrorFields,
+  SqliteQueryContext
+} from "./fields.js"
+import type {
+  SqliteErrorLike,
+  SqliteKnownErrorBase
+} from "./types.js"
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null
+
+const unwrapSqliteDriverCause = (cause: unknown): unknown => {
+  let current = cause
+  while (
+    isRecord(current) &&
+    "_tag" in current &&
+    current._tag === "SqlError" &&
+    "cause" in current
+  ) {
+    current = current.cause
+  }
+  return current
+}
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : undefined
+
+const asBoolean = (value: unknown): boolean | undefined =>
+  typeof value === "boolean" ? value : undefined
+
+const asNumber = (value: unknown): number | undefined => {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value
+  }
+  if (typeof value === "string" && /^[+-]?\d+$/.test(value.trim())) {
+    const parsed = Number(value.trim())
+    return Number.isFinite(parsed) ? parsed : undefined
+  }
+  return undefined
+}
+
+const normalizeFields = (error: Record<string, unknown>): SqliteErrorFields => ({
+  code: asString(error.code),
+  errno: asNumber(error.errno),
+  sqlState: asString(error.sqlState),
+  sqlMessage: asString(error.sqlMessage),
+  fatal: asBoolean(error.fatal),
+  sql: asString(error.sql),
+  syscall: asString(error.syscall),
+  address: asString(error.address),
+  port: asNumber(error.port),
+  hostname: asString(error.hostname)
+})
+
+export type { SqliteErrorLike } from "./types.js"
+
+/** Structured known SQLite error derived from the SQLite result-code catalog. */
+export type KnownSqliteError<Symbol extends SqliteErrorSymbol = SqliteErrorSymbol> =
+  SqliteKnownErrorBase & { readonly symbol: Symbol }
+
+/** Extracts the normalized SQLite error variant for a specific symbol. */
+export type KnownSqliteErrorBySymbol<Symbol extends SqliteErrorSymbol> = KnownSqliteError<Symbol>
+
+/** SQLite-like error whose symbol or number is not in the current catalog. */
+export type UnknownSqliteCodeError = Readonly<{
+  readonly _tag: "@sqlite/unknown/code"
+  readonly code?: string
+  readonly errno?: string | number
+  readonly message: string
+  readonly query?: SqliteQueryContext
+  readonly raw: SqliteErrorLike
+} & SqliteErrorFields>
+
+/** Fallback for non-SQLite driver failures in the SQLite executor path. */
+export type UnknownSqliteDriverError = Readonly<{
+  readonly _tag: "@sqlite/unknown/driver"
+  readonly message: string
+  readonly query?: SqliteQueryContext
+  readonly cause: unknown
+}>
+
+/** Any SQLite-specific driver failure surfaced by the SQLite executor. */
+export type SqliteDriverError =
+  | KnownSqliteError
+  | UnknownSqliteCodeError
+  | UnknownSqliteDriverError
+
+/** Runtime guard for objects that look like SQLite driver errors. */
+export const isSqliteErrorLike = (value: unknown): value is SqliteErrorLike =>
+  isRecord(value) &&
+  (
+    typeof value.code === "string" ||
+    typeof value.errno === "string" ||
+    typeof value.errno === "number" ||
+    typeof value.sqlState === "string" ||
+    typeof value.sqlMessage === "string" ||
+    typeof value.message === "string" ||
+    typeof value.fatal === "boolean"
+  )
+
+const errorMessageOf = (error: SqliteErrorLike): string =>
+  error.sqlMessage ?? error.message ?? "SQLite driver error"
+
+const numberOf = (error: SqliteErrorLike): string | undefined => {
+  if (typeof error.errno === "number" && Number.isFinite(error.errno)) {
+    return String(error.errno)
+  }
+  if (typeof error.errno === "string" && error.errno.trim() !== "") {
+    return error.errno
+  }
+  return undefined
+}
+
+const findDescriptor = (error: SqliteErrorLike): SqliteErrorDescriptor | undefined => {
+  if (typeof error.code === "string" && isSqliteErrorSymbol(error.code)) {
+    return getSqliteErrorDescriptor(error.code)
+  }
+  if (typeof error.code === "string" && isSqliteErrorNumber(error.code)) {
+    const matches = findSqliteErrorDescriptorsByNumberLoose(error.code)
+    if (matches?.length === 1) {
+      return matches[0]
+    }
+  }
+  const number = numberOf(error)
+  if (number !== undefined) {
+    const matches = findSqliteErrorDescriptorsByNumberLoose(number)
+    if (!matches || matches.length === 0) {
+      return undefined
+    }
+    if (matches.length === 1) {
+      return matches[0]
+    }
+    if (typeof error.code === "string") {
+      return matches.find((descriptor) => descriptor.symbol === error.code)
+    }
+  }
+  return undefined
+}
+
+const makeKnownSqliteError = (
+  descriptor: SqliteErrorDescriptor,
+  raw: SqliteErrorLike,
+  query?: SqliteQueryContext
+): SqliteKnownErrorBase => {
+  const fields = normalizeFields(raw as Record<string, unknown>)
+  return {
+    _tag: descriptor.tag,
+    category: descriptor.category,
+    number: descriptor.number,
+    symbol: descriptor.symbol,
+    messageTemplate: descriptor.messageTemplate,
+    message: errorMessageOf(raw),
+    query,
+    raw,
+    ...fields
+  } as SqliteKnownErrorBase
+}
+
+/** Normalizes an unknown failure into a structured SQLite driver error. */
+export const normalizeSqliteDriverError = (
+  cause: unknown,
+  query?: SqliteQueryContext | Renderer.RenderedQuery<any, "sqlite">
+): SqliteDriverError => {
+  const normalizedCause = unwrapSqliteDriverCause(cause)
+  const context = query === undefined
+    ? undefined
+    : "sql" in query
+      ? { sql: query.sql, params: query.params }
+      : query
+
+  if (!isSqliteErrorLike(normalizedCause)) {
+    return {
+      _tag: "@sqlite/unknown/driver",
+      message: normalizedCause instanceof Error ? normalizedCause.message : "Unknown SQLite driver failure",
+      query: context,
+      cause
+    } as UnknownSqliteDriverError
+  }
+
+  const descriptor = findDescriptor(normalizedCause)
+  if (descriptor !== undefined) {
+    return makeKnownSqliteError(descriptor, normalizedCause, context)
+  }
+
+  if (typeof normalizedCause.code === "string" || numberOf(normalizedCause) !== undefined) {
+    return {
+      _tag: "@sqlite/unknown/code",
+      code: asString(normalizedCause.code),
+      errno: normalizedCause.errno,
+      message: errorMessageOf(normalizedCause),
+      query: context,
+      raw: normalizedCause,
+      ...normalizeFields(normalizedCause as Record<string, unknown>)
+    } as UnknownSqliteCodeError
+  }
+
+  return {
+    _tag: "@sqlite/unknown/driver",
+    message: errorMessageOf(normalizedCause),
+    query: context,
+    cause
+  } as UnknownSqliteDriverError
+}
+
+/** Type guard for a specific SQLite catalog symbol. */
+export const hasSymbol = <Symbol extends SqliteErrorSymbol>(
+  error: SqliteDriverError | { readonly symbol?: string },
+  symbol: Symbol
+): error is KnownSqliteErrorBySymbol<Symbol> =>
+  "symbol" in error && error.symbol === symbol
+
+/** Type guard for a specific documented SQLite error number. */
+export const hasNumber = <Number extends SqliteErrorNumber>(
+  error: SqliteDriverError | { readonly number?: string; readonly errno?: string | number },
+  number: Number
+): error is KnownSqliteError & { readonly number: Number } =>
+  ("number" in error && error.number === number) ||
+  ("errno" in error && String(error.errno) === number)

package/src/sqlite/errors/requirements.ts

@@ -0,0 +1,71 @@
+import { read_query_capabilities, type QueryCapability, type QueryRequirement } from "../../internal/query-requirements.js"
+import type { SqliteQueryContext } from "./fields.js"
+import type {
+  KnownSqliteError,
+  SqliteDriverError,
+  UnknownSqliteCodeError,
+  UnknownSqliteDriverError
+} from "./normalize.js"
+
+export type SqliteQueryRequirement = Extract<QueryRequirement, "write" | "ddl" | "transaction" | "locking">
+
+export const sqlite_requirements_by_sqlstate_prefix = {
+  "23": ["write"]
+} as const satisfies Partial<Record<string, readonly SqliteQueryRequirement[]>>
+
+export type SqliteQueryRequirementsError = Readonly<{
+  readonly _tag: "@sqlite/unknown/query-requirements"
+  readonly message: string
+  readonly query?: SqliteQueryContext
+  readonly requiredCapabilities: readonly SqliteQueryRequirement[]
+  readonly actualCapabilities: readonly QueryCapability[]
+  readonly cause: SqliteDriverError
+}>
+
+export type SqliteReadQueryError =
+  | KnownSqliteError
+  | UnknownSqliteCodeError
+  | UnknownSqliteDriverError
+  | SqliteQueryRequirementsError
+
+const requiresWriteSqliteError = (error: SqliteDriverError): boolean =>
+  requirements_of_sqlite_error(error).length > 0
+
+const lookup_sqlite_requirements = (
+  sqlState: string
+): readonly SqliteQueryRequirement[] => {
+  const prefix = sqlState.slice(0, 2)
+  return prefix in sqlite_requirements_by_sqlstate_prefix
+    ? sqlite_requirements_by_sqlstate_prefix[prefix as keyof typeof sqlite_requirements_by_sqlstate_prefix]
+    : []
+}
+
+export const requirements_of_sqlite_error = (
+  error: SqliteDriverError
+): readonly SqliteQueryRequirement[] => {
+  if ("sqlState" in error && typeof error.sqlState === "string") {
+    return lookup_sqlite_requirements(error.sqlState)
+  }
+  if ("symbol" in error && (error.symbol === "SQLITE_READONLY" || error.symbol.startsWith("SQLITE_CONSTRAINT"))) {
+    return ["write"]
+  }
+  return []
+}
+
+export const narrowSqliteDriverErrorForReadQuery = (
+  error: SqliteDriverError
+): SqliteReadQueryError => {
+  const requiredCapabilities = requirements_of_sqlite_error(error)
+  if (!requiresWriteSqliteError(error)) {
+    return error as SqliteReadQueryError
+  }
+
+  return {
+    _tag: "@sqlite/unknown/query-requirements",
+    message: "SQLite driver error requires query capabilities not provided by this plan",
+    query: error.query,
+    requiredCapabilities,
+    actualCapabilities: read_query_capabilities,
+    cause: error
+  } satisfies SqliteQueryRequirementsError
+}

package/src/sqlite/errors/types.ts

@@ -0,0 +1,29 @@
+import type { SqliteErrorNumber, SqliteErrorSymbol, SqliteErrorTag } from "./catalog.js"
+import type { SqliteErrorFields, SqliteQueryContext } from "./fields.js"
+
+/** Raw SQLite-like error shape as commonly exposed by client libraries. */
+export interface SqliteErrorLike {
+  readonly code?: string
+  readonly errno?: string | number
+  readonly sqlState?: string
+  readonly sqlMessage?: string
+  readonly message?: string
+  readonly fatal?: boolean
+  readonly sql?: string
+  readonly syscall?: string
+  readonly address?: string
+  readonly port?: string | number
+  readonly hostname?: string
+}
+
+/** Broad known-SQLite error surface used by the normalizer return type. */
+export interface SqliteKnownErrorBase extends SqliteErrorFields {
+  readonly _tag: SqliteErrorTag
+  readonly category: "sqlite"
+  readonly number: SqliteErrorNumber
+  readonly symbol: SqliteErrorSymbol
+  readonly messageTemplate: string
+  readonly message: string
+  readonly query?: SqliteQueryContext
+  readonly raw: SqliteErrorLike
+}