@owlmeans/postgres-resource 0.1.15

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@owlmeans/postgres-resource",
+  "version": "0.1.15",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 204 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty",
+    "test": "bun test ./tests"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "ajv": "*",
+    "pg": "*"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.5.0",
+    "@owlmeans/basic-ids": "^0.1.15",
+    "@owlmeans/context": "^0.1.15",
+    "@owlmeans/resource": "^0.1.15",
+    "@owlmeans/server-context": "^0.1.15",
+    "@scure/base": "^1.1.9",
+    "drizzle-orm": "~0.45.2"
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@owlmeans/test-integration": "^0.1.15",
+    "@types/bun": "^1.3.14",
+    "@types/node": "^26.1.0",
+    "@types/pg": "^8.20.4",
+    "nodemon": "^3.1.14",
+    "pg": "^8.22.0",
+    "typescript": "^6.0.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,95 @@
+
+export const DEFAULT_DB_ALIAS = 'postgres'
+
+export const DEFAULT_PAGE_SIZE = 10
+
+/**
+ * Table that records which code-registered migrations have already been applied.
+ * Lives in the same Postgres schema as the resources it tracks, so dropping the
+ * schema drops the ledger with it.
+ */
+export const DEF_MIGRATIONS_TABLE = '_owlmeans_migrations'
+
+/** JSON Schema keyword carrying the Postgres specific overrides. */
+export const PG_KEYWORD = 'pg'
+
+/** Postgres `NAMEDATALEN - 1`. Identifiers past this are silently truncated by the server. */
+export const PG_MAX_IDENTIFIER = 63
+
+/** Property name that carries the record identity across every OwlMeans resource. */
+export const ID_FIELD = 'id'
+
+/** Fallback when a scalar property can't be mapped to anything more specific. */
+export const DEF_SQL_TYPE = 'text'
+
+export const DEF_JSON_TYPE = 'jsonb'
+
+/** Server side identity default for the implicit `id` primary key. */
+export const DEF_ID_DEFAULT = 'gen_random_uuid()::text'
+
+/**
+ * How far structure reconciliation is allowed to go.
+ *
+ * `additive` is the adoption path for a table this package didn't create: it adds what's
+ * missing but never retypes and never drops, so a first boot against an existing schema
+ * converges without touching data. Flip to `full` once the plan comes out empty.
+ */
+export enum PgAutoSync {
+  Full = 'full',
+  Additive = 'additive',
+  Off = 'off'
+}
+
+export enum PgIndexMethod {
+  BTree = 'btree',
+  Hash = 'hash',
+  Gin = 'gin',
+  Gist = 'gist',
+  Brin = 'brin',
+  SpGist = 'spgist'
+}
+
+export enum PgReferentialAction {
+  NoAction = 'no action',
+  Restrict = 'restrict',
+  Cascade = 'cascade',
+  SetNull = 'set null',
+  SetDefault = 'set default'
+}
+
+/**
+ * Postgres error codes the resource layer translates into framework errors. Sourced
+ * from the `pg` driver's `DatabaseError.code`.
+ */
+export enum PgErrorCode {
+  UniqueViolation = '23505',
+  ForeignKeyViolation = '23503',
+  NotNullViolation = '23502',
+  CheckViolation = '23514',
+  UndefinedTable = '42P01',
+  UndefinedColumn = '42703',
+  DuplicateTable = '42P07',
+  DuplicateColumn = '42701',
+  DuplicateObject = '42710',
+  CannotCoerce = '42846',
+  DatatypeMismatch = '42804',
+  InvalidTextRepresentation = '22P02',
+  StringDataRightTruncation = '22001',
+  NumericValueOutOfRange = '22003',
+  SerializationFailure = '40001',
+  DeadlockDetected = '40P01',
+  NoActiveTransaction = '25001'
+}
+
+/**
+ * Postgres reports scalar values of these types as strings to avoid precision loss.
+ * The marshaller converts them back using the resource's schema.
+ */
+export const STRING_RETURNING_TYPES = ['numeric', 'bigint', 'int8', 'decimal', 'money'] as const
+
+/** Built-in type OIDs the marshaller has to name to reach the driver's own parsers. */
+export enum PgTypeOid {
+  Date = 1082,
+  Timestamp = 1114,
+  TimestampTz = 1184
+}

package/src/declarations.ts

@@ -0,0 +1,41 @@
+import { createMigrationRegistry } from '@owlmeans/resource'
+import type { MigrationRegistry } from '@owlmeans/resource'
+import type { AnySchema } from 'ajv'
+
+import type { PgIndexSpec, PostgresTx } from './types.js'
+
+export interface PostgresDeclaration {
+  schema?: AnySchema
+  indexes: PgIndexSpec[]
+  migrations: MigrationRegistry<PostgresTx>
+}
+
+/**
+ * Per-alias declaration store, held at module scope rather than on the resource object.
+ *
+ * `reinitializeContext` rebuilds every resource, which drops anything a caller attached
+ * by chaining. Mongo lives with that by requiring the app to pass `makeCustomResource`
+ * and re-run the whole maker; migrations can't depend on that discipline, because losing
+ * one silently means a data transformation never runs. Keying the declarations by alias
+ * makes them survive any number of context switches.
+ */
+const declarations: Map<string, PostgresDeclaration> = new Map()
+
+export const getDeclaration = (alias: string): PostgresDeclaration => {
+  let declaration = declarations.get(alias)
+  if (declaration == null) {
+    declaration = { indexes: [], migrations: createMigrationRegistry<PostgresTx>() }
+    declarations.set(alias, declaration)
+  }
+
+  return declaration
+}
+
+/** Testing seam — drops every declaration so a spec can redeclare a resource from scratch. */
+export const resetDeclarations = (alias?: string): void => {
+  if (alias == null) {
+    declarations.clear()
+    return
+  }
+  declarations.delete(alias)
+}

package/src/errors.ts

@@ -0,0 +1,242 @@
+import { ResilientError } from '@owlmeans/error'
+import {
+  MisshapedRecord, RecordExists, ResourceError
+} from '@owlmeans/resource'
+
+import { PgErrorCode } from './consts.js'
+
+export class PostgresError extends ResourceError {
+  public static override typeName = `${ResourceError.typeName}PostgresError`
+
+  constructor(message: string = 'error') {
+    super(`postgres:${message}`)
+    this.type = PostgresError.typeName
+  }
+}
+
+/** Structure reconciliation failed. The message carries the offending statement. */
+export class PostgresSyncError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}SyncError`
+
+  constructor(message: string) {
+    super(`sync:${message}`)
+    this.type = PostgresSyncError.typeName
+  }
+}
+
+/**
+ * Postgres refused to cast a column to its new type. Fix it with `pg: { using: '<expr>' }`
+ * on the property, or with a `pre` migration that performs the ALTER by hand — after
+ * which reconciliation sees no drift and emits nothing.
+ */
+export class PostgresCastRequired extends PostgresSyncError {
+  public static override typeName = `${PostgresSyncError.typeName}CastRequired`
+
+  constructor(message: string) {
+    super(`cast-required:${message}`)
+    this.type = PostgresCastRequired.typeName
+  }
+}
+
+export class PostgresConstraintError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}ConstraintError`
+
+  constructor(message: string) {
+    super(`constraint:${message}`)
+    this.type = PostgresConstraintError.typeName
+  }
+}
+
+export class PostgresForeignKeyError extends PostgresConstraintError {
+  public static override typeName = `${PostgresConstraintError.typeName}ForeignKey`
+
+  constructor(message: string) {
+    super(`foreign-key:${message}`)
+    this.type = PostgresForeignKeyError.typeName
+  }
+}
+
+export class PostgresCheckError extends PostgresConstraintError {
+  public static override typeName = `${PostgresConstraintError.typeName}Check`
+
+  constructor(message: string) {
+    super(`check:${message}`)
+    this.type = PostgresCheckError.typeName
+  }
+}
+
+/** Serialization failure or deadlock — the caller may retry the whole transaction. */
+export class PostgresDeadlockError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}DeadlockError`
+
+  public readonly retryable: boolean = true
+
+  constructor(message: string) {
+    super(`deadlock:${message}`)
+    this.type = PostgresDeadlockError.typeName
+  }
+}
+
+/** A `{{alias}}` placeholder in custom SQL couldn't be resolved. */
+export class PostgresPlaceholderError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}PlaceholderError`
+
+  constructor(message: string) {
+    super(`placeholder:${message}`)
+    this.type = PostgresPlaceholderError.typeName
+  }
+}
+
+export class PostgresConnectionError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}ConnectionError`
+
+  constructor(message: string) {
+    super(`connection:${message}`)
+    this.type = PostgresConnectionError.typeName
+  }
+}
+
+/** The least-privilege admin path failed. */
+export class PostgresBootstrapError extends PostgresError {
+  public static override typeName = `${PostgresError.typeName}BootstrapError`
+
+  constructor(message: string) {
+    super(`bootstrap:${message}`)
+    this.type = PostgresBootstrapError.typeName
+  }
+}
+
+interface PgDriverError {
+  code?: string
+  detail?: string
+  hint?: string
+  severity?: string
+  constraint?: string
+  table?: string
+  column?: string
+  message?: string
+}
+
+const isDriverError = (error: unknown): error is PgDriverError =>
+  error != null && typeof error === 'object' && 'code' in error
+
+/**
+ * Reach the `pg` error inside whatever wrapped it.
+ *
+ * Drizzle raises `DrizzleQueryError` and hangs the driver error off `cause`, so a unique
+ * violation arriving through the query builder carries no `code` at the top level. Reading
+ * only the outer error is what makes the whole vocabulary below collapse to one opaque
+ * class on every CRUD path — and it is exactly the paths that go through Drizzle.
+ *
+ * The walk is bounded because `cause` chains can be circular.
+ */
+const unwrap = (error: unknown): unknown => {
+  let current = error
+  for (let depth = 0; depth < 8; depth += 1) {
+    if (isDriverError(current)) {
+      return current
+    }
+    const cause = (current as { cause?: unknown } | null)?.cause
+    if (cause == null || cause === current) {
+      return error
+    }
+    current = cause
+  }
+
+  return error
+}
+
+/**
+ * The framework's error marshalling preserves only type, message and stack, so the
+ * Postgres diagnostics have to travel inside the message. Downstream tooling — notably
+ * the viable-agent fixer, which retries on `42P01` / `42703` — classifies on exactly
+ * this text, so the code always leads.
+ *
+ * `where` is deliberately never included: it can echo bound parameter values.
+ *
+ * Exported so a wrapper can quote the diagnostics without also quoting the translated error's
+ * own type prefix, which would nest one error vocabulary inside another's message.
+ */
+export const describePgError = (error: unknown): string => {
+  const driver = unwrap(error)
+  if (!isDriverError(driver)) {
+    return error instanceof Error ? error.message : `${error}`
+  }
+
+  return describe(driver)
+}
+
+const describe = (error: PgDriverError): string => {
+  const parts = [error.code ?? 'unknown']
+  if (error.message != null) parts.push(error.message)
+  if (error.constraint != null) parts.push(`constraint=${error.constraint}`)
+  if (error.table != null) parts.push(`table=${error.table}`)
+  if (error.column != null) parts.push(`column=${error.column}`)
+  if (error.detail != null) parts.push(`detail=${error.detail}`)
+  if (error.hint != null) parts.push(`hint=${error.hint}`)
+  if (error.severity != null) parts.push(`severity=${error.severity}`)
+
+  return parts.join(' ')
+}
+
+/**
+ * Translate a raw `pg` driver error into the framework's error vocabulary, so a driver
+ * type never escapes the package. Errors that already are `ResilientError`s pass through
+ * untouched — the reconciler and the migration runner raise their own.
+ */
+export const pgErrorToResourceError = (error: unknown): Error => {
+  if (error instanceof ResilientError) {
+    return error
+  }
+  const driver = unwrap(error)
+  if (!isDriverError(driver)) {
+    return error instanceof Error ? error : new PostgresError(`${error}`)
+  }
+
+  const message = describe(driver)
+  const produce = (): Error => {
+    switch (driver.code) {
+      case PgErrorCode.UniqueViolation:
+        return new RecordExists(message)
+      case PgErrorCode.NotNullViolation:
+        return new MisshapedRecord(message)
+      case PgErrorCode.ForeignKeyViolation:
+        return new PostgresForeignKeyError(message)
+      case PgErrorCode.CheckViolation:
+        return new PostgresCheckError(message)
+      case PgErrorCode.DatatypeMismatch:
+      case PgErrorCode.CannotCoerce:
+        return new PostgresCastRequired(message)
+      case PgErrorCode.SerializationFailure:
+      case PgErrorCode.DeadlockDetected:
+        return new PostgresDeadlockError(message)
+      default:
+        break
+    }
+    if (driver.code != null && driver.code.startsWith('08')) {
+      return new PostgresConnectionError(message)
+    }
+    if (driver.code != null && driver.code.startsWith('23')) {
+      return new PostgresConstraintError(message)
+    }
+
+    return new PostgresError(message)
+  }
+
+  const produced = produce()
+  /** The *original* error, wrapper and all — unwrapping is for classification, not for loss. */
+  produced.cause = error
+
+  return produced
+}
+
+ResilientError.registerErrorClass(PostgresError)
+ResilientError.registerErrorClass(PostgresSyncError)
+ResilientError.registerErrorClass(PostgresCastRequired)
+ResilientError.registerErrorClass(PostgresConstraintError)
+ResilientError.registerErrorClass(PostgresForeignKeyError)
+ResilientError.registerErrorClass(PostgresCheckError)
+ResilientError.registerErrorClass(PostgresDeadlockError)
+ResilientError.registerErrorClass(PostgresPlaceholderError)
+ResilientError.registerErrorClass(PostgresConnectionError)
+ResilientError.registerErrorClass(PostgresBootstrapError)

package/src/helper.ts

@@ -0,0 +1,7 @@
+import type { AnySchema, JSONSchemaType } from 'ajv'
+
+/** Properties marked `secure: true` — the fields `lock()`/`unlock()` operate on by default. */
+export const getSchemaSecureFeilds = (schema: AnySchema): string[] =>
+  Object.entries((schema as JSONSchemaType<any>)?.properties ?? {})
+    .filter(([, property]) => (property as { secure?: boolean }).secure === true)
+    .map(([key]) => key)

package/src/index.ts

@@ -0,0 +1,7 @@
+export type * from './types.js'
+export * from './consts.js'
+export * from './declarations.js'
+export * from './errors.js'
+export * from './helper.js'
+export * from './resource.js'
+export * from './utils/index.js'