@edium/halifax 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -3,12 +3,39 @@
 All notable changes to this project are documented here. This project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.3]
+
+### Added
+
+- **`ConflictError`** — new `HttpError` subclass with HTTP status `409`. Exported from
+  the main package entry-point so application code can `throw new ConflictError()` in
+  hooks or custom repositories and have it serialised correctly.
+
+### Fixed
+
+- **409 Conflict on duplicate unique-key violations** — `PrismaAdapter` and `DrizzleAdapter`
+  now catch unique-constraint errors from the underlying ORM and re-throw them as
+  `ConflictError` (HTTP 409) instead of letting the raw ORM error propagate as an
+  unhandled 500.
+  - **Prisma**: catches `P2002` (unique constraint failed) on `createOne`, `createMany`,
+    `updateOne`, and both branches of `upsertOne`.
+  - **Drizzle**: catches PostgreSQL `23505`, MySQL `1062` / `ER_DUP_ENTRY`, and SQLite
+    `UNIQUE constraint failed` on `createOne`, `createMany`, and `updateOne`.
+- **`statusCodeMap` now includes `409 → 'CONFLICT'`** — previously, any `HttpError`
+  thrown with status `409` would have been serialised with `code: "INTERNAL_ERROR"`.
+
+### Changed
+
+- **OpenAPI spec** — write operations (`POST /{resource}`, `PATCH /{resource}`,
+  `PATCH /{resource}/{id}`, `PUT /{resource}/{id}`) now include a `409 Conflict` response
+  definition documenting that unique-constraint violations return this status.
+
 ## [2.2.2]
 
 ### Fixed
 
 - Removed the `preinstall` script from both `@edium/halifax` and `@edium/halifax-client`. The
-  script was a developer-convenience guard that enforced pnpm usage inside the monorepo, but because it shipped in the published package it caused npm (v7+) to prompt consumers with an  "approve build scripts" confirmation on every install. End-users no longer need to approve anything to install either package.
+  script was a developer-convenience guard that enforced pnpm usage inside the monorepo, but because it shipped in the published package it caused npm (v7+) to prompt consumers with an "approve build scripts" confirmation on every install. End-users no longer need to approve anything to install either package.
 
 ## [2.2.1]
 

package/README.md

@@ -157,21 +157,21 @@ app.listen(3000)
 
 ## Documentation
 
-| Guide                                                | Contents                                                                                                 |
-| ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| [README_CLIENT.md](./README_CLIENT.md) · [npm](https://www.npmjs.com/package/@edium/halifax-client) | `@edium/halifax-client` — install, transports, query builder, React & Vue TanStack Query examples |
-| [README_AUTOCRUD.md](./README_AUTOCRUD.md)           | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes            |
-| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md) | Prisma 7 (and 6) setup, `PrismaAdapter`, `DrizzleAdapter`, capabilities, custom repositories             |
-| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md) | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters                     |
-| [README_AUTH.md](./README_AUTH.md)                   | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, per-field `readRoles`/`writeRoles` |
-| [README_MULTITENANCY.md](./README_MULTITENANCY.md)   | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour            |
-| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)   | Query-builder payload, comparisons, nested filters, portable execution                                   |
-| [README_CACHE.md](./README_CACHE.md)                 | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header                          |
-| [README_HOOKS.md](./README_HOOKS.md)                 | Lifecycle hooks: `beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, and every other hook    |
-| [README_OPENAPI.md](./README_OPENAPI.md)             | OpenAPI 3.1 spec generation, Swagger UI, type introspection, security schemes, programmatic use          |
-| [README_TYPES.md](./README_TYPES.md)                 | All exported type aliases, enums (`SqlComparison`, `SqlOperator`, `SqlOrder`), and constants             |
-| [README_INTERFACES.md](./README_INTERFACES.md)       | All exported interfaces — resource, auth, HTTP, repository, cache, Prisma, Drizzle, query AST            |
-| [README_CLASSES.md](./README_CLASSES.md)             | All exported classes — auth strategies, HTTP adapters, ORM adapters, cache stores, error types           |
+| Guide                                                                                               | Contents                                                                                                 |
+| --------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| [README_CLIENT.md](./README_CLIENT.md) · [npm](https://www.npmjs.com/package/@edium/halifax-client) | `@edium/halifax-client` — install, transports, query builder, React & Vue TanStack Query examples        |
+| [README_AUTOCRUD.md](./README_AUTOCRUD.md)                                                          | Resource definitions, field flags, ID types, pagination, query-string filtering, error shapes            |
+| [README_REPO_ADAPTERS.md](./README_REPO_ADAPTERS.md)                                                | Prisma 7 (and 6) setup, `PrismaAdapter`, `DrizzleAdapter`, capabilities, custom repositories             |
+| [README_HTTP_ADAPTERS.md](./README_HTTP_ADAPTERS.md)                                                | Express, Fastify, HyperExpress & Ultimate Express adapters, and custom HTTP adapters                     |
+| [README_AUTH.md](./README_AUTH.md)                                                                  | Auth strategies (`ApiKey`, `JWT`, `Passport`), `requiredPermissions`, per-field `readRoles`/`writeRoles` |
+| [README_MULTITENANCY.md](./README_MULTITENANCY.md)                                                  | Tenant isolation: `tenant` options, auto-detection, scoping guarantees, fail-closed behaviour            |
+| [README_QUERYBUILDER.md](./README_QUERYBUILDER.md)                                                  | Query-builder payload, comparisons, nested filters, portable execution                                   |
+| [README_CACHE.md](./README_CACHE.md)                                                                | Read-through caching: in-memory & Redis stores, never-expire, cache-bust header                          |
+| [README_HOOKS.md](./README_HOOKS.md)                                                                | Lifecycle hooks: `beforeCreate`, `afterCreate`, `beforeReadMany`, `beforeQuery`, and every other hook    |
+| [README_OPENAPI.md](./README_OPENAPI.md)                                                            | OpenAPI 3.1 spec generation, Swagger UI, type introspection, security schemes, programmatic use          |
+| [README_TYPES.md](./README_TYPES.md)                                                                | All exported type aliases, enums (`SqlComparison`, `SqlOperator`, `SqlOrder`), and constants             |
+| [README_INTERFACES.md](./README_INTERFACES.md)                                                      | All exported interfaces — resource, auth, HTTP, repository, cache, Prisma, Drizzle, query AST            |
+| [README_CLASSES.md](./README_CLASSES.md)                                                            | All exported classes — auth strategies, HTTP adapters, ORM adapters, cache stores, error types           |
 
 ## Examples
 

package/dist/adapters/orm/drizzle/DrizzleAdapter.js

@@ -1,5 +1,19 @@
+import { ConflictError } from '../../../errors/ConflictError.js';
 import { count, eq, getTableColumns, and, inArray, asc, desc } from 'drizzle-orm';
 import { astToDrizzleWhere, astToDrizzleOrderBy } from './astToDrizzle.js';
+/** Detects unique constraint violations across PostgreSQL (23505), MySQL (1062/ER_DUP_ENTRY), and SQLite. */
+function isDuplicateError(error) {
+    if (typeof error !== 'object' || error === null)
+        return false;
+    const e = error;
+    if (e['code'] === '23505')
+        return true;
+    if (e['errno'] === 1062 || e['code'] === 'ER_DUP_ENTRY')
+        return true;
+    if (typeof e['message'] === 'string' && e['message'].includes('UNIQUE constraint failed'))
+        return true;
+    return false;
+}
 function drizzleTypeToOpenApi(col) {
     switch (col.dataType) {
         case 'string':
@@ -176,11 +190,18 @@ export class DrizzleAdapter {
         return { count: total, results: rows };
     }
     async createOne(data, _options) {
-        const rows = (await this.db
-            .insert(this.table)
-            .values(this.scope ? { ...data, [this.scope.field]: this.scope.value } : data)
-            .returning());
-        return rows[0];
+        try {
+            const rows = (await this.db
+                .insert(this.table)
+                .values(this.scope ? { ...data, [this.scope.field]: this.scope.value } : data)
+                .returning());
+            return rows[0];
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async createMany(data, _options) {
         if (!data.length)
@@ -188,18 +209,32 @@ export class DrizzleAdapter {
         const stamped = this.scope
             ? data.map((d) => ({ ...d, [this.scope.field]: this.scope.value }))
             : data;
-        const rows = (await this.db.insert(this.table).values(stamped).returning());
-        return rows;
+        try {
+            const rows = (await this.db.insert(this.table).values(stamped).returning());
+            return rows;
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async updateOne(id, data) {
         const idWhere = eq(this.columns[this.idField], id);
         const where = this.withScopeWhere(idWhere);
-        const rows = (await this.db
-            .update(this.table)
-            .set(this.stripScope(data))
-            .where(where)
-            .returning());
-        return rows[0] ?? null;
+        try {
+            const rows = (await this.db
+                .update(this.table)
+                .set(this.stripScope(data))
+                .where(where)
+                .returning());
+            return rows[0] ?? null;
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     async upsertOne(id, data) {
         const existing = await this.getOne(id);

package/dist/adapters/orm/prisma/PrismaAdapter.js

@@ -1,3 +1,4 @@
+import { ConflictError } from '../../../errors/ConflictError.js';
 import { NotImplementedError } from '../../../errors/NotImplementedError.js';
 import { NotFoundError } from '../../../errors/NotFoundError.js';
 import { ServerError } from '../../../errors/ServerError.js';
@@ -9,6 +10,13 @@ function isNotFoundError(error) {
         'code' in error &&
         error.code === 'P2025');
 }
+/** Returns true for Prisma's P2002 unique constraint violation. */
+function isDuplicateError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        error.code === 'P2002');
+}
 import { toSelect, toInclude, toOrderBy } from './helpers.js';
 function prismaTypeToOpenApi(prismaType) {
     switch (prismaType) {
@@ -247,7 +255,14 @@ export class PrismaAdapter {
      * @throws ServerError if the Prisma delegate does not support the create method.
      */
     async createOne(data) {
-        return (await this.delegate.create({ data: this.stampTenant(data) }));
+        try {
+            return (await this.delegate.create({ data: this.stampTenant(data) }));
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     /**
      * Creates multiple records in the database using the provided array of data objects.
@@ -260,7 +275,14 @@ export class PrismaAdapter {
         if (!this.delegate.createMany || this.returnCreated) {
             return await Promise.all(data.map((item) => this.createOne(item)));
         }
-        await this.delegate.createMany({ data: data.map((item) => this.stampTenant(item)) });
+        try {
+            await this.delegate.createMany({ data: data.map((item) => this.stampTenant(item)) });
+        }
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
         return [];
     }
     /**
@@ -291,6 +313,8 @@ export class PrismaAdapter {
         catch (error) {
             if (isNotFoundError(error))
                 return null;
+            if (isDuplicateError(error))
+                throw new ConflictError();
             throw error;
         }
     }
@@ -347,17 +371,31 @@ export class PrismaAdapter {
             if (existing && existing[this.scope.field] !== this.scope.value) {
                 throw new NotFoundError();
             }
+            try {
+                return (await this.delegate.upsert({
+                    where: { [this.idField]: id },
+                    create: this.stampTenant(data),
+                    update: this.stripTenant(data)
+                }));
+            }
+            catch (error) {
+                if (isDuplicateError(error))
+                    throw new ConflictError();
+                throw error;
+            }
+        }
+        try {
             return (await this.delegate.upsert({
                 where: { [this.idField]: id },
-                create: this.stampTenant(data),
-                update: this.stripTenant(data)
+                create: data,
+                update: data
             }));
         }
-        return (await this.delegate.upsert({
-            where: { [this.idField]: id },
-            create: data,
-            update: data
-        }));
+        catch (error) {
+            if (isDuplicateError(error))
+                throw new ConflictError();
+            throw error;
+        }
     }
     /**
      * Deletes a single record identified by its ID. If the record does not exist, it returns false.

package/dist/core/handlerUtils.js

@@ -13,6 +13,7 @@ const statusCodeMap = {
     404: 'NOT_FOUND',
     405: 'METHOD_NOT_ALLOWED',
     406: 'NOT_ACCEPTABLE',
+    409: 'CONFLICT',
     415: 'UNSUPPORTED_MEDIA_TYPE',
     422: 'UNPROCESSABLE_ENTITY',
     501: 'NOT_IMPLEMENTED'

package/dist/errors/ConflictError.d.ts

@@ -0,0 +1,5 @@
+import { HttpError } from './HttpError.js';
+/** Thrown when a write conflicts with an existing record — e.g. a duplicate unique field (HTTP 409). */
+export declare class ConflictError extends HttpError {
+    constructor(message?: string, details?: unknown);
+}

package/dist/errors/ConflictError.js

@@ -0,0 +1,8 @@
+import { HttpError } from './HttpError.js';
+/** Thrown when a write conflicts with an existing record — e.g. a duplicate unique field (HTTP 409). */
+export class ConflictError extends HttpError {
+    constructor(message = 'Conflict', details) {
+        super(message, 409, details);
+        this.name = 'ConflictError';
+    }
+}

package/dist/index.d.ts

@@ -10,6 +10,7 @@ export * from './core/types.js';
 export * from './core/validation.js';
 export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
+export * from './errors/ConflictError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
 export * from './errors/HttpError.js';

package/dist/index.js

@@ -10,6 +10,7 @@ export * from './core/types.js';
 export * from './core/validation.js';
 export * from '@edium/halifax-types';
 export * from './errors/AuthenticationError.js';
+export * from './errors/ConflictError.js';
 export * from './errors/AuthorizationError.js';
 export * from './errors/BadRequestError.js';
 export * from './errors/HttpError.js';

package/dist/openapi/specGenerator.js

@@ -262,6 +262,7 @@ const badRequestError = errorRef('Bad Request — malformed query string, invali
 const notFoundError = errorRef('Not Found — the record with the given ID does not exist.');
 const unprocessableError = errorRef('Unprocessable Entity — request body contains unknown or non-writable fields.');
 const notImplementedError = errorRef('Not Implemented — the underlying repository does not support this operation.');
+const conflictError = errorRef('Conflict — the write was rejected because it would violate a unique constraint.');
 // ─── Main export ──────────────────────────────────────────────────────────────
 export function generateOpenApiSpec(resources, options = {}) {
     const globalEnvelope = normalizeEnvelope(options.envelope);
@@ -458,6 +459,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         content: { 'application/json': { schema: { oneOf: [singleResponse, arrayResponse] } } }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     ...commonErrors,
                     ...writeErrors
@@ -538,6 +540,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     '501': notImplementedError,
                     ...commonErrors,
@@ -697,6 +700,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                     },
                     '400': badRequestError,
                     '404': notFoundError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     ...commonErrors,
                     ...writeErrors
@@ -733,6 +737,7 @@ export function generateOpenApiSpec(resources, options = {}) {
                         }
                     },
                     '400': badRequestError,
+                    '409': conflictError,
                     '422': unprocessableError,
                     '501': notImplementedError,
                     ...commonErrors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edium/halifax",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Auto-generate type-safe REST CRUD APIs from your data models. Adapter-driven: Express/Fastify/HyperExpress, Prisma (PostgreSQL, MySQL, MariaDB, SQL Server, CockroachDB, SQLite), JWT/API-key auth, multi-tenancy, a dynamic query builder, and pluggable Redis caching.",
   "author": "David LaTour <david@edium.com>",
   "homepage": "https://github.com/splayfee/halifax#readme",