Copy page

DAL Library

Error Handling

Error Handling

Relevant source files

The following files were used as context for generating this wiki page:

• docs/ai/dal-usage-guide.md
• src/errors/errors.ts
• test/repository-negative.test.ts

The Primebrick DAL utilizes a framework-agnostic error hierarchy designed to provide stable, machine-readable error codes. This design ensures that the DAL remains decoupled from transport-layer concerns such as HTTP status codes or NATS error protocols. Consumers are responsible for mapping these internal errors to their respective boundary responses (e.g., mapping NOT_FOUND to a 404 Not Found in a REST API) src/errors/errors.ts:1-7.

Error Hierarchy

All custom errors in the library inherit from the DalError base class, which enforces the presence of a code string src/errors/errors.ts:10-16.

Class	Code	Trigger Condition
NotFoundError	NOT_FOUND	A finder (e.g., findById) returns zero rows when throwIfNotFound is enabled src/errors/errors.ts:19-24.
MultipleRowsError	MULTIPLE_ROWS	A single-row finder unexpectedly returns more than one record src/errors/errors.ts:27-32.
UnknownColumnError	UNKNOWN_COLUMN	A write operation contains a property not defined in the entity metadata src/errors/errors.ts:35-40.
ValidationError	VALIDATION	Invalid input parameters, such as empty update objects or invalid pagination src/errors/errors.ts:43-48.

Logic Flow: From Code Entity to Error Space

The following diagram illustrates how specific repository methods transition from the "Code Entity Space" into the "Error Space" based on execution results.

Repository Error Mapping

Code
graph TD
    subgraph "Code Entity Space"
        R["Repository"]
        F["findById()"]
        U["update()"]
        P["findByPage()"]
    end

    subgraph "Error Space"
        NF["NotFoundError (NOT_FOUND)"]
        VE["ValidationError (VALIDATION)"]
        UC["UnknownColumnError (UNKNOWN_COLUMN)"]
    end

    R --> F
    R --> U
    R --> P

    F -- "0 rows returned" --> NF
    U -- "matchBy key not found" --> NF
    U -- "empty updates object" --> VE
    U -- "property missing in @Entity" --> UC
    P -- "page <= 0" --> VE

Sources: src/errors/errors.ts:1-49, test/repository-negative.test.ts:42-200, docs/ai/dal-usage-guide.md:138-160

Implementation Details

NotFoundError

This is the most common error. By default, findById, findByUUID, and find have throwIfNotFound: true docs/ai/dal-usage-guide.md:143-144. The error message typically includes the entity table name and the identifier that failed to match to assist in debugging test/repository-negative.test.ts:42-51.

ValidationError

The DAL performs "pre-flight" checks before generating SQL to prevent database-level errors for known invalid states:

• Empty Writes: Attempting to add an empty object or update with only undefined values test/repository-negative.test.ts:115-155.
• Pagination Guards: findByPage enforces page > 0 and recordsPerPage > 0 test/repository-negative.test.ts:157-173.

UnknownColumnError

To prevent SQL injection and data corruption, the DAL validates every key in a write payload against the @Entity metadata. If a key is passed that is not decorated with @Column (or is marked with @IsNotColumn), this error is thrown test/repository-negative.test.ts:177-200.

MultipleRowsError

While rare for Primary Key lookups, this error is a safety mechanism for find(entity, fields) or findById if the underlying schema does not strictly enforce uniqueness as expected by the application logic src/errors/errors.ts:26-32.

Data Flow: Error Propagation

The DAL does not swallow database driver errors (from pg). If a constraint violation (like UniqueViolation) occurs in PostgreSQL, the raw DatabaseError from the pg driver is propagated to the caller. The custom hierarchy above specifically covers logical DAL failures.

Error Propagation and Handling Boundary

Code
sequenceDiagram
    participant C as Consumer (e.g. Express Controller)
    participant R as Repository
    participant D as PostgreSQL

    C->>R: findById(User, 999)
    R->>D: SELECT ... WHERE id = 999
    D-->>R: 0 rows
    Note over R: Check throwIfNotFound == true
    R-->>C: throw NotFoundError("NOT_FOUND")
    
    Note over C: Mapping Boundary
    alt is NotFoundError
        C->>C: return 404
    else is ValidationError
        C->>C: return 400
    else is DatabaseError (pg)
        C->>C: return 500
    end

Sources: src/errors/errors.ts:1-7, docs/ai/dal-usage-guide.md:143-160, test/repository-negative.test.ts:42-52

Silent Failures

Certain operations are designed to fail silently (return empty results) rather than throw when the input set is empty:

• addMany, upsertMany, deleteMany, and updateMany return an empty array [] if passed an empty input array test/repository-negative.test.ts:204-225.
• delete and hardDelete do NOT throw if the record was already missing, provided they are called in a context where existence is not strictly required (though standard repository delete by UUID defaults to throwing if the target is missing) test/repository-negative.test.ts:86-111.

Sources: test/repository-negative.test.ts:204-225, src/errors/errors.ts:1-49

---