porsager / porsager/postgres

Improve error handling documentation and TypeScript support

Open
#1,132 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
JavaScript
Stars
8.7k
Forks
374
Avg merge
11d 16h
Merged PRs (30d)
1

Description

Hello and thank you for your time and dedication to postgress-js.

The current error handling implementation uses Object.assign to dynamically add properties to error objects (see errors.js). While the README mentions following the PostgreSQL error format, it doesn't document:

  • Which property contains the error code
  • The complete structure of error properties
  • How to properly type-check these errors in TypeScript

Suggestions

1. Enhanced Documentation

Document the complete error object structure, including:

  • Available properties (code, message, detail, hint, etc.)
  • Which properties are guaranteed vs optional
  • Examples of accessing error information
2. Class-Based Error Types

Consider replacing Object.assign with proper error classes:

class PostgresError extends Error {
  code: string;
  severity: string;
  detail?: string;
  hint?: string;
  // ... other well-defined properties
}

I know there is already a PostgressError extending error, but it is not clear what it is use for (I only saw one or two references in the entire codebase) and everything else is just Error.generic which has all the problems I mentioned.

Benefits:

  • Better TypeScript autocomplete and type safety
  • Clear API surface for error handling
  • Improved developer experience

This would significantly improve the TypeScript developer experience.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with deno/src/errors.js and the README, then inspect the existing PostgressError references and the Error.generic handling described in the issue. Done should mean the error properties, their optionality, and TypeScript handling are clearly documented, with any agreed error-type changes covered by tests or type checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, typescript
Domain
backend-api-design, documentation
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.