fix: features contract + FTS + test updates

Author: jddunn

README.md

@@ -496,6 +496,8 @@ await exporter.exportToFile('/backups/snapshot.db');
 const bytes = await exporter.exportToBytes();
 ```
 
+On Postgres, `features.exporter` requires a Node runtime plus an adapter that was created with a connection string in `adapter.options.connectionString`, since `pg_dump` runs out-of-process.
+
 ## CI, Releases, and Badges
 
 - GitHub Actions workflows:

src/core/contracts/features.ts

@@ -12,6 +12,31 @@ import { BrowserBlobCodec } from '../../codecs/BrowserBlobCodec.js';
 import { SqliteFileExporter } from '../../exporters/SqliteFileExporter.js';
 import { PostgresExporter } from '../../exporters/PostgresExporter.js';
 
+interface PostgresAdapterOptionsLike {
+  connectionString?: string;
+  host?: string;
+  port?: number;
+  database?: string;
+  user?: string;
+  password?: string;
+  ssl?: boolean | object;
+}
+
+function extractPostgresConnectionString(adapter: StorageAdapter): string | undefined {
+  const options = (adapter as StorageAdapter & { options?: PostgresAdapterOptionsLike }).options;
+  if (!options) return undefined;
+  if (options.connectionString) return options.connectionString;
+  if (!options.database) return undefined;
+
+  const host = options.host ?? 'localhost';
+  const port = options.port ?? 5432;
+  const user = options.user ? encodeURIComponent(options.user) : '';
+  const password = options.password ? `:${encodeURIComponent(options.password)}` : '';
+  const auth = user ? `${user}${password}@` : '';
+  const sslQuery = options.ssl ? '?sslmode=require' : '';
+  return `postgresql://${auth}${host}:${port}/${options.database}${sslQuery}`;
+}
+
 /**
  * Bundle of platform-aware database features.
  *
@@ -34,11 +59,14 @@ export interface StorageFeatures {
 export function createStorageFeatures(adapter: StorageAdapter): StorageFeatures {
   const isPostgres = adapter.kind === 'postgres';
   const isBrowser = typeof window !== 'undefined' && typeof window.document !== 'undefined';
+  const postgresConnectionString = isPostgres ? extractPostgresConnectionString(adapter) : undefined;
 
   return {
     dialect: isPostgres ? new PostgresDialect() : new SqliteDialect(),
     fts: isPostgres ? new PostgresFts() : new SqliteFts5(),
     blobCodec: isBrowser ? new BrowserBlobCodec() : new NodeBlobCodec(),
-    exporter: isPostgres ? new PostgresExporter() : new SqliteFileExporter(adapter),
+    exporter: isPostgres
+      ? new PostgresExporter(postgresConnectionString)
+      : new SqliteFileExporter(adapter),
   };
 }

src/fts/PostgresFts.ts

@@ -11,13 +11,15 @@ export class PostgresFts implements IFullTextSearch {
   /** The content table is stored during createIndex for use by other methods. */
   private _contentTable = '';
   private _columns: string[] = [];
+  private _lang = 'english';
 
   createIndex(config: { table: string; columns: string[]; contentTable?: string; tokenizer?: string }): string {
     const ct = config.contentTable ?? config.table;
     this._contentTable = ct;
     this._columns = config.columns;
     const colConcat = config.columns.map((c) => `COALESCE(${c}, '')`).join(" || ' ' || ");
     const lang = this._tokenizerToLang(config.tokenizer);
+    this._lang = lang;
 
     return [
       `ALTER TABLE ${ct} ADD COLUMN IF NOT EXISTS _tsv tsvector`,
@@ -27,24 +29,26 @@ export class PostgresFts implements IFullTextSearch {
   }
 
   matchClause(_indexName: string, queryPlaceholder: string): string {
-    return `_tsv @@ plainto_tsquery('english', ${queryPlaceholder})`;
+    return `_tsv @@ plainto_tsquery('${this._lang}', ${queryPlaceholder})`;
   }
 
   rankExpression(_indexName: string, queryPlaceholder?: string): string {
     const qp = queryPlaceholder ?? '$1';
-    return `ts_rank(_tsv, plainto_tsquery('english', ${qp}))`;
+    return `ts_rank(_tsv, plainto_tsquery('${this._lang}', ${qp}))`;
   }
 
   rebuildCommand(_indexName: string): string {
     const ct = this._contentTable;
     const colConcat = this._columns.map((c) => `COALESCE(${c}, '')`).join(" || ' ' || ");
-    return `UPDATE ${ct} SET _tsv = to_tsvector('english', ${colConcat})`;
+    return `UPDATE ${ct} SET _tsv = to_tsvector('${this._lang}', ${colConcat})`;
   }
 
-  syncInsert(_indexName: string, rowIdExpr: string, columns: string[]): string {
+  syncInsert(_indexName: string, _rowIdExpr: string, columns: string[]): string {
     const ct = this._contentTable;
-    const colConcat = columns.map((c) => `COALESCE(${c}, '')`).join(" || ' ' || ");
-    return `UPDATE ${ct} SET _tsv = to_tsvector('english', ${colConcat}) WHERE rowid = ${rowIdExpr}`;
+    const colConcat = columns
+      .map((_, index) => `COALESCE($${index + 2}, '')`)
+      .join(" || ' ' || ");
+    return `UPDATE ${ct} SET _tsv = to_tsvector('${this._lang}', ${colConcat}) WHERE id = $1`;
   }
 
   sanitizeQuery(input: string): string {

tests/features.spec.ts

@@ -9,7 +9,7 @@ import { SqliteFileExporter } from '../src/exporters/SqliteFileExporter.js';
 import { PostgresExporter } from '../src/exporters/PostgresExporter.js';
 import type { StorageAdapter } from '../src/core/contracts/index.js';
 
-function mockAdapter(kind: string): StorageAdapter {
+function mockAdapter(kind: string, extra: Record<string, unknown> = {}): StorageAdapter {
   return {
     kind,
     capabilities: new Set(),
@@ -20,6 +20,7 @@ function mockAdapter(kind: string): StorageAdapter {
     exec: async () => {},
     transaction: async (fn) => fn({} as StorageAdapter),
     close: async () => {},
+    ...extra,
   } as StorageAdapter;
 }
 
@@ -39,9 +40,15 @@ describe('createStorageFeatures', () => {
   });
 
   it('returns PostgresDialect + PostgresFts for postgres adapter', () => {
-    const features = createStorageFeatures(mockAdapter('postgres'));
+    const features = createStorageFeatures(
+      mockAdapter('postgres', {
+        options: { connectionString: 'postgresql://user:pass@localhost:5432/testdb' },
+      }),
+    );
     expect(features.dialect).toBeInstanceOf(PostgresDialect);
     expect(features.fts).toBeInstanceOf(PostgresFts);
     expect(features.exporter).toBeInstanceOf(PostgresExporter);
+    expect((features.exporter as PostgresExporter & { connectionString?: string })['connectionString'])
+      .toBe('postgresql://user:pass@localhost:5432/testdb');
   });
 });

tests/fts.spec.ts

@@ -61,9 +61,11 @@ describe('PostgresFts', () => {
       table: 'memory_traces_fts',
       columns: ['content', 'tags'],
       contentTable: 'memory_traces',
+      tokenizer: 'simple',
     });
     expect(ddl).toContain('ADD COLUMN IF NOT EXISTS _tsv tsvector');
     expect(ddl).toContain('USING GIN');
+    expect(ddl).toContain("to_tsvector('simple'");
   });
 
   it('matchClause generates @@ expression', () => {
@@ -77,6 +79,20 @@ describe('PostgresFts', () => {
     expect(expr).toContain('ts_rank');
   });
 
+  it('syncInsert updates by id using bound values instead of rowid', () => {
+    fts.createIndex({
+      table: 'memory_traces_fts',
+      columns: ['content', 'tags'],
+      contentTable: 'memory_traces',
+      tokenizer: 'simple',
+    });
+    const sql = fts.syncInsert('memory_traces_fts', '?', ['content', 'tags']);
+    expect(sql).toContain('WHERE id = $1');
+    expect(sql).toContain("COALESCE($2, '')");
+    expect(sql).toContain("COALESCE($3, '')");
+    expect(sql).toContain("to_tsvector('simple'");
+  });
+
   it('rebuildCommand generates UPDATE with to_tsvector', () => {
     const cmd = fts.rebuildCommand('memory_traces_fts');
     expect(cmd).toContain('UPDATE');

tests/postgres.dialect.integration.spec.ts

@@ -170,6 +170,24 @@ describeIf('Postgres dialect integration', () => {
     expect(rows.length).toBeGreaterThanOrEqual(1);
   });
 
+  it('fts.syncInsert updates the tsvector column for newly inserted rows', async () => {
+    await adapter.run(
+      'INSERT INTO test_memory_traces (id, content, tags) VALUES ($1, $2, $3)',
+      ['t7', 'event sourcing and domain events', '["ddd"]'],
+    );
+
+    await adapter.run(
+      features.fts.syncInsert('test_memory_traces_fts', '$1', ['content', 'tags']),
+      ['t7', 'event sourcing and domain events', '["ddd"]'],
+    );
+
+    const rows = await adapter.all<{ id: string }>(
+      `SELECT id FROM test_memory_traces WHERE ${features.fts.matchClause('test_memory_traces_fts', '$1')}`,
+      ['event sourcing'],
+    );
+    expect(rows.some((row) => row.id === 't7')).toBe(true);
+  });
+
   it('blobCodec roundtrip works', async () => {
     const testVec = [0.1, 0.2, -0.5, 1.0];
     const encoded = features.blobCodec.encode(testVec);