@stonyx/orm 0.2.1-alpha.4 → 0.2.1-alpha.40

package/src/{orm-request.js → orm-request.ts}

@@ -1,11 +1,57 @@
 import { Request } from '@stonyx/rest-server';
-import Orm, { createRecord, updateRecord, store } from '@stonyx/orm';
+import Orm, { store, createRecord, updateRecord } from '@stonyx/orm';
 import { camelCaseToKebabCase } from '@stonyx/utils/string';
-import { pluralize } from './utils.js';
+import { getPluralName } from './plural-registry.js';
 import { getBeforeHooks, getAfterHooks } from './hooks.js';
 import config from 'stonyx/config';
+import type { OrmRecord } from './types/orm-types.js';
+import { isOrmRecord } from './utils.js';
+
+interface OrmRequest$ extends Request {
+  protocol?: string;
+  method: string;
+  params: { [key: string]: string };
+  body?: { [key: string]: unknown };
+  query?: { [key: string]: string };
+  get(header: string): string;
+}
+
+interface RelationshipInfo {
+  type: 'belongsTo' | 'hasMany';
+  isArray: boolean;
+}
+
+interface Filter {
+  path: string[];
+  value: string;
+}
+
+interface HookContext {
+  model: string;
+  operation: string;
+  request: OrmRequest$;
+  params: { [key: string]: string };
+  body?: { [key: string]: unknown };
+  query?: { [key: string]: string };
+  state: { [key: string]: unknown };
+  oldState?: unknown;
+  recordId?: string | number;
+  response?: unknown;
+  record?: unknown;
+  records?: unknown;
+  [key: string]: unknown;
+}
+
+interface JsonApiResponse {
+  data: unknown;
+  links?: { [key: string]: string };
+  included?: unknown[];
+}
 
-const methodAccessMap = {
+type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+type HandlerFn = (request: OrmRequest$, state: { [key: string]: unknown }) => unknown | Promise<unknown>;
+
+const methodAccessMap: { [key: string]: string } = {
   GET: 'read',
   POST: 'create',
   DELETE: 'delete',
@@ -15,25 +61,25 @@ const methodAccessMap = {
 const WRITE_OPERATIONS = new Set(['create', 'update', 'delete']);
 
 // Helper to detect relationship type from function
-function getRelationshipInfo(property) {
+function getRelationshipInfo(property: unknown): RelationshipInfo | null {
   if (typeof property !== 'function') return null;
-  const fnStr = property.toString();
-  if (fnStr.includes(`getRelationships('belongsTo',`)) {
+  const relType = (property as { __relationshipType?: string }).__relationshipType;
+  if (relType === 'belongsTo') {
     return { type: 'belongsTo', isArray: false };
   }
-  if (fnStr.includes(`getRelationships('hasMany',`)) {
+  if (relType === 'hasMany') {
     return { type: 'hasMany', isArray: true };
   }
   return null;
 }
 
 // Helper to introspect model relationships
-function getModelRelationships(modelName) {
+function getModelRelationships(modelName: string): { [key: string]: RelationshipInfo } {
   const { modelClass } = Orm.instance.getRecordClasses(modelName);
   if (!modelClass) return {};
 
-  const model = new modelClass(modelName);
-  const relationships = {};
+  const model = new (modelClass as new (name: string) => { [key: string]: unknown })(modelName);
+  const relationships: { [key: string]: RelationshipInfo } = {};
 
   for (const [key, property] of Object.entries(model)) {
     if (key.startsWith('__')) continue;
@@ -47,21 +93,28 @@ function getModelRelationships(modelName) {
 }
 
 // Helper to build base URL from request
-function getBaseUrl(request) {
+function getBaseUrl(request: OrmRequest$): string {
   const protocol = request.protocol || 'http';
   const host = request.get('host');
   return `${protocol}://${host}`;
 }
 
-function getId({ id }) {
-  if (isNaN(id)) return id;
+function getId(params: { id?: string; [key: string]: unknown }): string | number {
+  const id = params.id;
+  if (!id) return '';
+  if (isNaN(id as unknown as number)) return id;
 
   return parseInt(id);
 }
 
-function buildResponse(data, includeParam, recordOrRecords, options = {}) {
+function buildResponse(
+  data: unknown,
+  includeParam: string | undefined,
+  recordOrRecords: OrmRecord | OrmRecord[],
+  options: { links?: { [key: string]: string }; baseUrl?: string } = {}
+): JsonApiResponse {
   const { links, baseUrl } = options;
-  const response = { data };
+  const response: JsonApiResponse = { data };
 
   // Add top-level links
   if (links) {
@@ -75,7 +128,7 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
 
   const includedRecords = collectIncludedRecords(recordOrRecords, includes);
   if (includedRecords.length > 0) {
-    response.included = includedRecords.map(record => record.toJSON({ baseUrl }));
+    response.included = includedRecords.map(record => record.toJSON?.({ baseUrl }));
   }
 
   return response;
@@ -83,17 +136,18 @@ function buildResponse(data, includeParam, recordOrRecords, options = {}) {
 
 /**
  * Recursively traverse an include path and collect related records
- * @param {Array<Record>} currentRecords - Records to process at current depth
- * @param {Array<string>} includePath - Full path array (e.g., ['owner', 'pets', 'traits'])
- * @param {number} depth - Current depth in the path
- * @param {Map} seen - Deduplication map
- * @param {Array} included - Accumulator for included records
  */
-function traverseIncludePath(currentRecords, includePath, depth, seen, included) {
+function traverseIncludePath(
+  currentRecords: OrmRecord[],
+  includePath: string[],
+  depth: number,
+  seen: Map<string, Set<string | number>>,
+  included: OrmRecord[]
+): void {
   if (depth >= includePath.length) return; // Reached end of path
 
   const relationshipName = includePath[depth];
-  const nextRecords = [];
+  const nextRecords: OrmRecord[] = [];
 
   for (const record of currentRecords) {
     if (!record.__relationships) continue;
@@ -103,24 +157,27 @@ function traverseIncludePath(currentRecords, includePath, depth, seen, included)
     if (!relatedRecords) continue;
 
     // Handle both belongsTo (single) and hasMany (array)
-    const recordsToProcess = Array.isArray(relatedRecords)
-      ? relatedRecords
-      : [relatedRecords];
+    const recordsToProcess: OrmRecord[] = Array.isArray(relatedRecords)
+      ? relatedRecords.filter(isOrmRecord)
+      : isOrmRecord(relatedRecords) ? [relatedRecords] : [];
 
     for (const relatedRecord of recordsToProcess) {
       if (!relatedRecord) continue;
 
+      if (!relatedRecord.__model) continue;
       const type = relatedRecord.__model.__name;
-      const id = relatedRecord.id;
+      const id = relatedRecord.id as string | number;
 
       // Initialize Set for this type if needed
-      if (!seen.has(type)) {
-        seen.set(type, new Set());
+      let seenIds = seen.get(type);
+      if (!seenIds) {
+        seenIds = new Set();
+        seen.set(type, seenIds);
       }
 
       // Check if we've already seen this type+id combination
-      if (!seen.get(type).has(id)) {
-        seen.get(type).add(id);
+      if (!seenIds.has(id)) {
+        seenIds.add(id);
         included.push(relatedRecord);
         nextRecords.push(relatedRecord); // Prepare for next depth level
       } else if (depth < includePath.length - 1) {
@@ -136,15 +193,15 @@ function traverseIncludePath(currentRecords, includePath, depth, seen, included)
   }
 }
 
-function collectIncludedRecords(data, includes) {
+function collectIncludedRecords(data: OrmRecord | OrmRecord[], includes: string[][]): OrmRecord[] {
   if (!includes || includes.length === 0) return [];
   if (!data) return [];
 
-  const seen = new Map(); // Map<type, Set<id>> for deduplication
-  const included = [];
+  const seen = new Map<string, Set<string | number>>(); // Map<type, Set<id>> for deduplication
+  const included: OrmRecord[] = [];
 
   // Normalize to array for consistent processing
-  const records = Array.isArray(data) ? data : [data];
+  const records: OrmRecord[] = Array.isArray(data) ? data : [data];
 
   // Process each include path
   for (const includePath of includes) {
@@ -154,18 +211,18 @@ function collectIncludedRecords(data, includes) {
   return included;
 }
 
-function parseInclude(includeParam) {
+function parseInclude(includeParam: string | undefined): string[][] {
   if (!includeParam || typeof includeParam !== 'string') return [];
 
   return includeParam
     .split(',')
     .map(rel => rel.trim())
     .filter(rel => rel.length > 0)
-    .map(rel => rel.split('.')); // Parse nested paths: "owner.pets" → ["owner", "pets"]
+    .map(rel => rel.split('.')); // Parse nested paths: "owner.pets" -> ["owner", "pets"]
 }
 
-function parseFields(query) {
-  const fields = new Map();
+function parseFields(query: { [key: string]: string } | undefined): Map<string, Set<string>> {
+  const fields = new Map<string, Set<string>>();
   if (!query) return fields;
 
   for (const [key, value] of Object.entries(query)) {
@@ -180,8 +237,8 @@ function parseFields(query) {
   return fields;
 }
 
-function parseFilters(query) {
-  const filters = [];
+function parseFilters(query: { [key: string]: string } | undefined): Filter[] {
+  const filters: Filter[] = [];
   if (!query) return filters;
 
   for (const [key, value] of Object.entries(query)) {
@@ -194,15 +251,15 @@ function parseFilters(query) {
   return filters;
 }
 
-function createFilterPredicate(filters) {
+function createFilterPredicate(filters: Filter[]): ((record: { [key: string]: unknown }) => boolean) | null {
   if (filters.length === 0) return null;
 
-  return (record) => filters.every(({ path, value }) => {
-    let current = record;
+  return (record: { [key: string]: unknown }) => filters.every(({ path, value }) => {
+    let current: unknown = record;
 
     for (const segment of path) {
       if (current == null) return false;
-      current = current[segment];
+      current = (current as { [key: string]: unknown })[segment];
     }
 
     return String(current) === value;
@@ -210,18 +267,22 @@ function createFilterPredicate(filters) {
 }
 
 export default class OrmRequest extends Request {
-  constructor({ model, access }) {
-    super(...arguments);
+  model: string;
+  access: (request: unknown) => AccessMethod;
+  handlers: { [key: string]: { [key: string]: HandlerFn } };
+
+  constructor({ model, access }: { model: string; access: (request: unknown) => AccessMethod }) {
+    super(...arguments as unknown as unknown[]);
 
     this.model = model;
     this.access = access;
-    const pluralizedModel = pluralize(model);
+    const pluralizedModel = getPluralName(model);
 
     const modelRelationships = getModelRelationships(model);
 
     // Define raw handlers first
-    const getCollectionHandler = async (request, { filter: accessFilter }) => {
-      const allRecords = await store.findAll(model);
+    const getCollectionHandler: HandlerFn = async (request, { filter: accessFilter }) => {
+      const allRecords = (await store.findAll(model)).filter(isOrmRecord);
 
       const queryFilters = parseFilters(request.query);
       const queryFilterPredicate = createFilterPredicate(queryFilters);
@@ -229,11 +290,11 @@ export default class OrmRequest extends Request {
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       let recordsToReturn = allRecords;
-      if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter);
-      if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate);
+      if (accessFilter) recordsToReturn = recordsToReturn.filter(accessFilter as (record: OrmRecord) => boolean);
+      if (queryFilterPredicate) recordsToReturn = recordsToReturn.filter(queryFilterPredicate as (record: OrmRecord) => boolean);
 
       const baseUrl = getBaseUrl(request);
-      const data = recordsToReturn.map(record => record.toJSON({ fields: modelFields, baseUrl }));
+      const data = recordsToReturn.map(record => record.toJSON?.({ fields: modelFields, baseUrl }));
 
       return buildResponse(data, request.query?.include, recordsToReturn, {
         links: { self: `${baseUrl}/${pluralizedModel}` },
@@ -241,22 +302,27 @@ export default class OrmRequest extends Request {
       });
     };
 
-    const getSingleHandler = async (request) => {
-      const record = await store.find(model, getId(request.params));
+    const getSingleHandler: HandlerFn = async (request) => {
+      const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
       if (!record) return 404;
 
       const fieldsMap = parseFields(request.query);
       const modelFields = fieldsMap.get(pluralizedModel) || fieldsMap.get(model);
 
       const baseUrl = getBaseUrl(request);
-      return buildResponse(record.toJSON({ fields: modelFields, baseUrl }), request.query?.include, record, {
+      return buildResponse(record.toJSON?.({ fields: modelFields, baseUrl }), request.query?.include, record, {
         links: { self: `${baseUrl}/${pluralizedModel}/${request.params.id}` },
         baseUrl
       });
     };
 
-    const createHandler = async ({ body, query }) => {
-      const { type, id, attributes, relationships: rels } = body?.data || {};
+    const createHandler: HandlerFn = async ({ body, query }) => {
+      const { type, id, attributes, relationships: rels } = (body?.data || {}) as {
+        type?: string;
+        id?: string | number;
+        attributes?: { [key: string]: unknown };
+        relationships?: { [key: string]: { data?: { id?: string | number } } };
+      };
 
       if (!type) return 400; // Bad request
 
@@ -273,27 +339,34 @@ export default class OrmRequest extends Request {
         for (const [key, value] of Object.entries(rels)) {
           const relData = value?.data;
           if (relData && relData.id !== undefined) {
-            sanitizedAttributes[key] = relData.id;
+            (sanitizedAttributes as { [key: string]: unknown })[key] = relData.id;
           }
         }
       }
 
       const recordAttributes = id !== undefined ? { id, ...sanitizedAttributes } : sanitizedAttributes;
-      const record = createRecord(model, recordAttributes, { serialize: false });
+      const created = createRecord(model, recordAttributes as { [key: string]: unknown }, { serialize: false });
+      const record = isOrmRecord(created) ? created : null;
+      if (!record) return 500;
 
-      return { data: record.toJSON({ fields: modelFields }) };
+      return { data: record.toJSON?.({ fields: modelFields }) };
     };
 
-    const updateHandler = async ({ body, params }) => {
-      const record = await store.find(model, getId(params));
-      const { attributes, relationships: rels } = body?.data || {};
+    const updateHandler: HandlerFn = async ({ body, params }) => {
+      const found = await store.find(model, getId(params));
+      if (!found || !isOrmRecord(found)) return 404;
+      const record = found;
+      const { attributes, relationships: rels } = (body?.data || {}) as {
+        attributes?: { [key: string]: unknown };
+        relationships?: { [key: string]: { data?: { id?: string | number } } };
+      };
 
       if (!attributes && !rels) return 400; // Bad request
 
       // Apply attribute updates 1 by 1 to utilize built-in transform logic, ignore id key
       if (attributes) {
         for (const [key, value] of Object.entries(attributes)) {
-          if (!record.hasOwnProperty(key)) continue;
+          if (!Object.hasOwn(record, key)) continue;
           if (key === 'id') continue;
 
           record[key] = value
@@ -302,7 +375,7 @@ export default class OrmRequest extends Request {
 
       // Apply relationship updates via updateRecord to properly resolve references
       if (rels) {
-        const relUpdates = {};
+        const relUpdates: { [key: string]: unknown } = {};
         for (const [key, value] of Object.entries(rels)) {
           const relData = value?.data;
           if (relData && relData.id !== undefined) {
@@ -310,42 +383,48 @@ export default class OrmRequest extends Request {
           }
         }
         if (Object.keys(relUpdates).length > 0) {
-          updateRecord(record, relUpdates);
+          updateRecord(record as never, relUpdates);
         }
       }
 
-      return { data: record.toJSON() };
+      return { data: record.toJSON?.() };
     };
 
-    const deleteHandler = ({ params }) => {
+    const deleteHandler: HandlerFn = ({ params }) => {
       store.remove(model, getId(params));
       return 204;
     };
 
     // Wrap handlers with hooks
+    const isView = Orm.instance?.isView?.(model);
+
     this.handlers = {
       get: {
         '/': this._withHooks('list', getCollectionHandler),
         '/:id': this._withHooks('get', getSingleHandler),
         ...this._generateRelationshipRoutes(model, pluralizedModel, modelRelationships)
       },
-      patch: {
+    };
+
+    // Views are read-only -- no write endpoints
+    if (!isView) {
+      this.handlers.patch = {
         '/:id': this._withHooks('update', updateHandler)
-      },
-      post: {
+      };
+      this.handlers.post = {
         '/': this._withHooks('create', createHandler)
-      },
-      delete: {
+      };
+      this.handlers.delete = {
         '/:id': this._withHooks('delete', deleteHandler)
-      }
+      };
     }
   }
 
   // Wraps a handler with before/after hook execution
-  _withHooks(operation, handler) {
-    return async (request, state) => {
+  private _withHooks(operation: string, handler: HandlerFn): HandlerFn {
+    return async (request: OrmRequest$, state: { [key: string]: unknown }) => {
       // Build context object for hooks
-      const context = {
+      const context: HookContext = {
         model: this.model,
         operation,
         request,
@@ -357,7 +436,7 @@ export default class OrmRequest extends Request {
 
       // Capture old state for operations that modify data
       if (operation === 'update' || operation === 'delete') {
-        const existingRecord = await store.find(this.model, getId(request.params));
+        const existingRecord = await store.find(this.model, getId(request.params)) as OrmRecord | undefined;
         if (existingRecord) {
           // Deep copy the record's data to preserve old state
           context.oldState = JSON.parse(JSON.stringify(existingRecord.__data || existingRecord));
@@ -379,23 +458,25 @@ export default class OrmRequest extends Request {
       // Execute main handler
       const response = await handler(request, state);
 
-      // Persist to MySQL for write operations
-      if (Orm.instance.mysqlDb && WRITE_OPERATIONS.has(operation)) {
-        await Orm.instance.mysqlDb.persist(operation, this.model, context, response);
+      // Persist to SQL database for write operations
+      const sqlDb = Orm.instance.sqlDb;
+      if (sqlDb && WRITE_OPERATIONS.has(operation)) {
+        await sqlDb.persist(operation, this.model, context, response);
       }
 
       // Add response and relevant records to context
       context.response = response;
 
-      if (operation === 'get' && response?.data && !Array.isArray(response.data)) {
+      if (operation === 'get' && (response as JsonApiResponse)?.data && !Array.isArray((response as JsonApiResponse).data)) {
         context.record = await store.find(this.model, getId(request.params));
-      } else if (operation === 'list' && response?.data) {
+      } else if (operation === 'list' && (response as JsonApiResponse)?.data) {
         context.records = await store.findAll(this.model);
-      } else if (operation === 'create' && response?.data?.id) {
+      } else if (operation === 'create' && (response as JsonApiResponse)?.data && ((response as { data: { id?: unknown } }).data.id)) {
         // For create, get the record from store using the ID from the response
-        const recordId = isNaN(response.data.id) ? response.data.id : parseInt(response.data.id);
+        const responseData = (response as { data: { id: string | number } }).data;
+        const recordId = isNaN(responseData.id as unknown as number) ? responseData.id : parseInt(responseData.id as string);
         context.record = store.get(this.model, recordId);
-      } else if (operation === 'update' && response?.data) {
+      } else if (operation === 'update' && (response as JsonApiResponse)?.data) {
         context.record = store.get(this.model, getId(request.params));
       } else if (operation === 'delete') {
         // For delete, the record may no longer exist, but we have oldState
@@ -409,35 +490,40 @@ export default class OrmRequest extends Request {
 
       // Auto-save DB after write operations when configured
       if (config.orm.db.autosave === 'onUpdate' && WRITE_OPERATIONS.has(operation)) {
-        await Orm.db.save();
+        await (Orm.db as { save(): Promise<void> }).save();
       }
 
       return response;
     };
   }
 
-  _generateRelationshipRoutes(model, pluralizedModel, modelRelationships) {
-    const routes = {};
+  private _generateRelationshipRoutes(
+    model: string,
+    pluralizedModel: string,
+    modelRelationships: { [key: string]: RelationshipInfo }
+  ): { [key: string]: HandlerFn } {
+    const routes: { [key: string]: HandlerFn } = {};
 
     for (const [relationshipName, info] of Object.entries(modelRelationships)) {
       // Dasherize the relationship name for URL paths (e.g., accessLinks -> access-links)
       const dasherizedName = camelCaseToKebabCase(relationshipName);
 
       // Related resource route: GET /:id/{relationship}
-      routes[`/:id/${dasherizedName}`] = async (request) => {
-        const record = await store.find(model, getId(request.params));
+      routes[`/:id/${dasherizedName}`] = async (request: OrmRequest$) => {
+        const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
-        let data;
+        let data: unknown;
         if (info.isArray) {
           // hasMany - return array
-          data = (relatedData || []).map(r => r.toJSON({ baseUrl }));
+          const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
+          data = related.map(r => r.toJSON?.({ baseUrl }));
         } else {
           // belongsTo - return single or null
-          data = relatedData ? relatedData.toJSON({ baseUrl }) : null;
+          data = isOrmRecord(relatedData) ? relatedData.toJSON?.({ baseUrl }) : null;
         }
 
         return {
@@ -447,20 +533,27 @@ export default class OrmRequest extends Request {
       };
 
       // Relationship linkage route: GET /:id/relationships/{relationship}
-      routes[`/:id/relationships/${dasherizedName}`] = async (request) => {
-        const record = await store.find(model, getId(request.params));
+      routes[`/:id/relationships/${dasherizedName}`] = async (request: OrmRequest$) => {
+        const record = await store.find(model, getId(request.params)) as OrmRecord | undefined;
         if (!record) return 404;
 
         const relatedData = record.__relationships[relationshipName];
         const baseUrl = getBaseUrl(request);
 
-        let data;
+        let data: unknown;
         if (info.isArray) {
           // hasMany - return array of linkage objects
-          data = (relatedData || []).map(r => ({ type: r.__model.__name, id: r.id }));
+          const related = Array.isArray(relatedData) ? relatedData.filter(isOrmRecord) : [];
+          data = related
+            .filter((r): r is OrmRecord & { __model: { __name: string } } => Boolean(r.__model))
+            .map(r => ({ type: r.__model.__name, id: r.id }));
         } else {
           // belongsTo - return single linkage or null
-          data = relatedData ? { type: relatedData.__model.__name, id: relatedData.id } : null;
+          if (isOrmRecord(relatedData) && relatedData.__model) {
+            data = { type: relatedData.__model.__name, id: relatedData.id };
+          } else {
+            data = null;
+          }
         }
 
         return {
@@ -474,7 +567,7 @@ export default class OrmRequest extends Request {
     }
 
     // Catch-all for invalid relationship names on related resource route
-    routes[`/:id/:relationship`] = async (request) => {
+    routes[`/:id/:relationship`] = async (request: OrmRequest$) => {
       const record = await store.find(model, getId(request.params));
       if (!record) return 404;
 
@@ -483,7 +576,7 @@ export default class OrmRequest extends Request {
     };
 
     // Catch-all for invalid relationship names on relationship linkage route
-    routes[`/:id/relationships/:relationship`] = async (request) => {
+    routes[`/:id/relationships/:relationship`] = async (request: OrmRequest$) => {
       const record = await store.find(model, getId(request.params));
       if (!record) return 404;
 
@@ -493,7 +586,7 @@ export default class OrmRequest extends Request {
     return routes;
   }
 
-  auth(request, state) {
+  auth(request: OrmRequest$, state: { [key: string]: unknown }): number | undefined {
     const access = this.access(request);
 
     if (!access) return 403;

package/src/plural-registry.ts

@@ -0,0 +1,12 @@
+import { pluralize } from './utils.js';
+
+const registry: Map<string, string> = new Map();
+
+export function registerPluralName(modelName: string, modelClass: { pluralName?: string }): void {
+  const plural = modelClass.pluralName || pluralize(modelName);
+  registry.set(modelName, plural);
+}
+
+export function getPluralName(modelName: string): string {
+  return registry.get(modelName) || pluralize(modelName);
+}

package/src/postgres/connection.ts

@@ -0,0 +1,48 @@
+import type { Pool as PgPool } from 'pg';
+import { validateIdentifier } from './query-builder.js';
+
+interface PgConfig {
+  host: string;
+  port: number;
+  user: string;
+  password: string;
+  database: string;
+  connectionLimit: number;
+}
+
+let pool: PgPool | null = null;
+
+/**
+ * Create or return the singleton pg Pool.
+ */
+export async function getPool(pgConfig: PgConfig, extensions: string[] = ['vector']): Promise<PgPool> {
+  if (pool) return pool;
+
+  const { default: pg } = await import('pg');
+
+  pool = new pg.Pool({
+    host: pgConfig.host,
+    port: pgConfig.port,
+    user: pgConfig.user,
+    password: pgConfig.password,
+    database: pgConfig.database,
+    max: pgConfig.connectionLimit,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 10000,
+  });
+
+  // Enable requested PostgreSQL extensions
+  for (const ext of extensions) {
+    validateIdentifier(ext, 'extension name');
+    await pool.query(`CREATE EXTENSION IF NOT EXISTS "${ext}"`);
+  }
+
+  return pool;
+}
+
+export async function closePool(): Promise<void> {
+  if (!pool) return;
+
+  await pool.end();
+  pool = null;
+}