Add type definitions for PostgreSQL parser options

.changeset/add-parser-pg-type-definitions.md

@@ -0,0 +1,9 @@
+---
+'@electric-sql/client': minor
+---
+
+Add type definitions for PostgreSQL types in the parser option.
+
+Introduces a `BuiltInPgType` union type that lists all built-in PostgreSQL type names, providing IDE autocomplete and IntelliSense support when defining custom parsers. The `Parser` type now suggests known PostgreSQL types while still allowing custom types like enums, domains, and composite types.
+
+Also exports `BuiltInPgType`, `Parser`, `ParseFunction`, `pgArrayParser`, and `defaultParser` from the package for easier use by consumers.

packages/typescript-client/src/index.ts

@@ -16,3 +16,10 @@ export {
   snakeToCamel,
   camelToSnake,
 } from './column-mapper'
+export {
+  type BuiltInPgType,
+  type Parser,
+  type ParseFunction,
+  pgArrayParser,
+  defaultParser,
+} from './parser'

packages/typescript-client/src/parser.ts

@@ -11,12 +11,106 @@ type NullableParseFunction<Extensions = never> = (
   value: NullableToken,
   additionalInfo?: Omit<ColumnInfo, `type` | `dims`>
 ) => Value<Extensions>
+
 /**
+ * Built-in PostgreSQL type names that can be used as parser keys.
+ * This provides autocomplete/IntelliSense support for common PostgreSQL types.
+ *
+ * Note: Custom types (enums, domains, composite types) can still be used as keys
+ * even though they are not listed here.
+ */
+export type BuiltInPgType =
+  // Numeric Types
+  | `int2`
+  | `int4`
+  | `int8`
+  | `float4`
+  | `float8`
+  | `numeric`
+  | `decimal`
+  | `money`
+  | `oid`
+  // Character Types
+  | `char`
+  | `bpchar`
+  | `varchar`
+  | `text`
+  | `citext`
+  | `name`
+  // Binary Type
+  | `bytea`
+  // Date/Time Types
+  | `date`
+  | `time`
+  | `timetz`
+  | `timestamp`
+  | `timestamptz`
+  | `interval`
+  // Boolean
+  | `bool`
+  // Geometric Types
+  | `point`
+  | `line`
+  | `lseg`
+  | `box`
+  | `path`
+  | `polygon`
+  | `circle`
+  // Network Types
+  | `cidr`
+  | `inet`
+  | `macaddr`
+  | `macaddr8`
+  // Bit String Types
+  | `bit`
+  | `varbit`
+  // Text Search Types
+  | `tsvector`
+  | `tsquery`
+  // UUID
+  | `uuid`
+  // XML
+  | `xml`
+  // JSON Types
+  | `json`
+  | `jsonb`
+  // Range Types
+  | `int4range`
+  | `int8range`
+  | `numrange`
+  | `tsrange`
+  | `tstzrange`
+  | `daterange`
+  // Multirange Types (PostgreSQL 14+)
+  | `int4multirange`
+  | `int8multirange`
+  | `nummultirange`
+  | `tsmultirange`
+  | `tstzmultirange`
+  | `datemultirange`
+
+/**
+ * Parser type mapping PostgreSQL type names to parse functions.
+ *
+ * Provides autocomplete for built-in PostgreSQL types while still allowing
+ * custom types like enums, domains, and composite types.
+ *
  * @typeParam Extensions - Additional types that can be parsed by this parser beyond the standard SQL types.
  *                         Defaults to no additional types.
+ *
+ * @example
+ * ```ts
+ * const parser: Parser = {
+ *   // Built-in types get autocomplete
+ *   timestamptz: (value) => new Date(value),
+ *   uuid: (value) => value,
+ *   // Custom types (enums, domains) also work
+ *   my_enum: (value) => value as MyEnum,
+ * }
+ * ```
  */
 export type Parser<Extensions = never> = {
-  [key: string]: ParseFunction<Extensions>
+  [key in BuiltInPgType | (string & {})]?: ParseFunction<Extensions>
 }
 
 export type TransformFunction<Extensions = never> = (
@@ -29,7 +123,7 @@ const parseBigInt = (value: string) => BigInt(value)
 const parseJson = (value: string) => JSON.parse(value)
 const identityParser: ParseFunction = (v: string) => v
 
-export const defaultParser: Parser = {
+export const defaultParser = {
   int2: parseNumber,
   int4: parseNumber,
   int8: parseBigInt,
@@ -38,7 +132,7 @@ export const defaultParser: Parser = {
   float8: parseNumber,
   json: parseJson,
   jsonb: parseJson,
-}
+} satisfies Parser
 
 // Taken from: https://github.com/electric-sql/pglite/blob/main/packages/pglite/src/types.ts#L233-L279
 export function pgArrayParser<Extensions>(