Copy page

DAL Library

Test Suite Coverage

Test Suite Coverage

Relevant source files

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

• test/benchmark/bulk-benchmark.test.ts
• test/dal-timeout.test.ts
• test/dal.test.ts
• test/repository-bulk.test.ts
• test/repository-crud.test.ts
• test/repository-negative.test.ts
• test/repository-streaming.test.ts
• test/repository-types.test.ts

The @primebrick/dal-pg test suite is designed to ensure the reliability of the Data Access Layer (DAL) across various operational scenarios, including standard CRUD, high-volume bulk operations, complex type mappings, and resource management under stress. The suite utilizes Vitest for test execution and requires a live PostgreSQL instance (configured via DATABASE_URL) to perform integration testing against real database behaviors test/dal.test.ts:31-34.

Core Test Files and Coverage

1. Repository CRUD and Finders

File: test/repository-crud.test.ts This file covers the fundamental data access patterns of the Repository class using SimpleTestEntity test/repository-crud.test.ts:4-12.

• Write Lifecycle: Verifies that add correctly inserts rows, returns them with RETURNING *, and automatically stamps audit fields (created_by, version, etc.) test/repository-crud.test.ts:32-62.
• Finder Logic: Validates findById, findByUUID, and find (with DSL filters) test/repository-crud.test.ts:72-142.
• Soft-Delete Visibility: Tests findAll behavior regarding the deletedRecords option (EXCLUDED, INCLUDED, ONLY) to ensure soft-deleted records are filtered correctly by default test/repository-crud.test.ts:164-195.
• Pagination: Ensures findByPage correctly utilizes window functions to return both the data subset and the total_records count test/repository-crud.test.ts:199-201.

2. Bulk Operations

File: test/repository-bulk.test.ts Focuses on high-efficiency write methods and the internal batching logic test/repository-bulk.test.ts:12-14.

• addMany: Validates auto-batching when row counts exceed internal limits and ensures all rows receive audit stamps test/repository-bulk.test.ts:32-79.
• upsertMany: Tests the INSERT ON CONFLICT logic, verifying that existing rows have their version incremented while new rows are created test/repository-bulk.test.ts:97-136.
• updateMany: Exercises the TEMP TABLE strategy. It verifies that the DAL creates a temporary table, populates it, and performs a single join-based UPDATE test/repository-bulk.test.ts:181-202.
• deleteMany: Validates bulk soft-deletion using the ANY() array operator test/repository-bulk.test.ts:148-169.

3. Type Mapping Matrix

File: test/repository-types.test.ts Ensures parity between JavaScript types and PostgreSQL OIDs test/repository-types.test.ts:12-14.

JS Type	PG Type	Test Coverage
number	INTEGER	Round-trips, negative values, and zero test/repository-types.test.ts:31-99.
bigint	BIGINT	Verified via native BigInt and INT8 parser registration test/repository-types.test.ts:103-150.
boolean	BOOLEAN	Round-trips for true/false test/repository-types.test.ts:153-197.
string	VARCHAR / TEXT	UTF-8 support and null handling test/repository-types.test.ts:201-223.
Date	TIMESTAMPTZ	Precision and timezone preservation.

4. Streaming and AsyncIterables

File: test/repository-streaming.test.ts Validates the integration with pg-query-stream test/repository-streaming.test.ts:12-14.

• Memory Efficiency: Verifies that findAll with stream: true returns an AsyncIterable rather than an array test/repository-streaming.test.ts:30-46.
• Consumption: Ensures large result sets (e.g., 100+ rows) can be iterated without buffering the entire set into Node.js memory test/repository-streaming.test.ts:71-91.

5. Negative Paths and Error Handling

File: test/repository-negative.test.ts Ensures the DAL fails gracefully and provides actionable error codes test/repository-negative.test.ts:18-21.

• NotFoundError: Thrown when primary keys or UUIDs do not exist test/repository-negative.test.ts:42-63.
• ValidationError: Thrown for empty insert/update payloads or invalid pagination parameters (e.g., page 0) test/repository-negative.test.ts:115-174.
• UnknownColumnError: Triggered when an entity object contains properties not decorated as columns test/repository-negative.test.ts:177-200.
• Silent Failures: Confirms that bulk operations with empty arrays return [] instead of throwing test/repository-negative.test.ts:204-225.

6. Dal Gateway and Lifecycle

File: test/dal.test.ts Tests the Dal singleton, pool management, and session initialization test/dal.test.ts:19-25.

• Singleton Guard: Ensures getDal() returns a consistent instance and enforces connection string immutability test/dal.test.ts:23-24.
• Pool Lifecycle: Tests close() re-entrancy, the 10-second graceful shutdown timeout, and post-closure rejection of queries test/dal.test.ts:77-136.
• onConnect: Verifies that every new connection executes the session setup (setting search_path, statement_timeout, and application_name) test/dal.test.ts:140-166.

7. Timeout Management

File: test/dal-timeout.test.ts Detailed verification of statement_timeout behavior and leakage prevention test/dal-timeout.test.ts:31-35.

• Per-call Overrides: Verifies that timeoutMs in bulk options or withClient successfully emits SET LOCAL statement_timeout test/dal-timeout.test.ts:133-145.
• Leakage Prevention: Crucial test ensuring that if a client is returned to the pool after a custom timeout, the next consumer sees the global default, not the overridden value test/dal-timeout.test.ts:157-179.
• Execution Abort: Confirms that pg_sleep() calls exceeding the timeoutMs are successfully terminated by the database test/dal-timeout.test.ts:181-193.

8. Performance Benchmarks

File: test/benchmark/bulk-benchmark.test.ts Measures throughput at scales of 100, 1K, 10K, and (optionally) 1M rows test/benchmark/bulk-benchmark.test.ts:98-101.

• Throughput Metrics: Tracks records-per-second (RPS) for updateMany and upsertMany across simple and complex (primitive-heavy) tables test/benchmark/bulk-benchmark.test.ts:66-84.

System Interaction Diagrams

Data Flow: Write Operations and Validation

This diagram maps the flow from a Repository call to the database, highlighting where validation and error entities are triggered.

Title: Repository Write Flow and Error Mapping

Code
graph TD
    subgraph "Natural Language Space"
        UserAction["User attempts to update record"]
        MissingRecord["Record does not exist"]
        InvalidFields["Invalid column names provided"]
    end

    subgraph "Code Entity Space"
        RepoCall["Repository.update()"]
        MetaCheck["getEntityPersistenceMeta()"]
        SqlBuild["buildUpdateQuery()"]
        DalExec["Dal.rawSql()"]
        
        NotFoundErr["NotFoundError (code: 'NOT_FOUND')"]
        UnknownColErr["UnknownColumnError (code: 'UNKNOWN_COLUMN')"]
    end

    UserAction --> RepoCall
    RepoCall --> MetaCheck
    MetaCheck -- "Invalid property" --> UnknownColErr
    RepoCall --> SqlBuild
    SqlBuild --> DalExec
    DalExec -- "0 rows affected" --> NotFoundErr
    MissingRecord -.-> NotFoundErr
    InvalidFields -.-> UnknownColErr

Sources: test/repository-negative.test.ts:76-84, test/repository-negative.test.ts:187-200

Connection Lifecycle and Timeout Reset

This diagram illustrates how the Dal ensures that statement_timeout settings do not leak between different requests.

Title: Connection Pool Timeout Safety

Code
graph TD
    subgraph "Pool Management"
        Pool["pg.Pool"]
        Client["pg.PoolClient"]
    end

    subgraph "Test Scenarios (dal-timeout.test.ts)"
        T1["Test: withClient({timeoutMs: 1000})"]
        T2["Test: subsequent withClient()"]
    end

    T1 -->|Acquire| Client
    Client -->|Exec| SetLocal["SET LOCAL statement_timeout = 1000"]
    T1 -->|Release| Pool
    Pool -->|Reset| ResetCall["SET statement_timeout = default (30000)"]
    
    T2 -->|Acquire| Client
    Client -->|Verify| CheckSetting["SELECT current_setting('statement_timeout')"]
    CheckSetting -- "Returns 30000" --> Success["No Leakage Detected"]

Sources: test/dal-timeout.test.ts:157-179, test/dal.test.ts:140-166

Summary of Coverage Files

File	Focus	Primary Entities
repository-crud.test.ts	Basic Operations	SimpleTestEntity
repository-bulk.test.ts	Batch Processing	SimpleTestEntity
repository-types.test.ts	PG/JS Serialization	TypeTestEntity
repository-streaming.test.ts	Memory Management	SimpleTestEntity
repository-negative.test.ts	Error Paths	All
dal.test.ts	Pool & Lifecycle	N/A
dal-timeout.test.ts	Transaction Safety	N/A
bulk-benchmark.test.ts	Performance	BenchSimpleEntity, BenchPrimitivesEntity

Sources: test/repository-crud.test.ts:1-12, test/repository-bulk.test.ts:1-12, test/repository-types.test.ts:1-12, test/repository-streaming.test.ts:1-12, test/repository-negative.test.ts:1-21, test/dal.test.ts:1-25, test/dal-timeout.test.ts:1-35, test/benchmark/bulk-benchmark.test.ts:1-22

---