@hozon/adapter 0.1.0 → 0.2.0

package/lib/index.d.ts

@@ -1,3 +1,3 @@
 export { AbstractPostgresAdapter, type PostgresTypes } from './postgres.js';
 export { AbstractSQLiteAdapter, type SQLiteTypes } from './sqlite.js';
-export type { AbstractAdapter, Adapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, CreatedAtColumn, Functions, NullOrderingTerm, OrderDirection, UpdatedAtColumn, } from './types.js';
+export type { AbstractAdapter, Adapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, CreatedAtColumn, Functions, NullOrderingTerm, OrderDirection, SearchCapability, SearchEntry, SearchHit, SearchIndex, SearchQuery, UpdatedAtColumn, } from './types.js';

package/lib/postgres.d.ts

@@ -1,11 +1,12 @@
 import type { Expression, RawBuilder } from 'kysely';
-import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection } from './types.js';
+import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection, SearchCapability } from './types.js';
 export type PostgresTypes = {
     Binary: Uint8Array;
     JSON: unknown;
     Timestamp: string;
 };
 export declare abstract class AbstractPostgresAdapter<T extends AdapterTypes = PostgresTypes> implements AbstractAdapter<T> {
+    search: SearchCapability;
     kind: "postgres";
     functions: Functions;
     types: ColumnTypes;

package/lib/postgres.js

@@ -1,5 +1,49 @@
 import { sql } from 'kysely';
+import { assertSearchFields, assertSearchIndex } from './search.js';
 export class AbstractPostgresAdapter {
+    search = {
+        async createIndex (db, params) {
+            assertSearchIndex(params.index);
+            assertSearchFields(params.fields, params.index);
+            await sql`CREATE TABLE IF NOT EXISTS ${sql.table(params.index)} (
+        entry_key TEXT PRIMARY KEY REFERENCES ${sql.table(params.table)} (${sql.id(params.key)}) ON DELETE CASCADE,
+        search_vector tsvector
+      )`.execute(db);
+            // Hash the compiled physical name to stay below PostgreSQL's 63-byte limit.
+            let hash = 14695981039346656037n;
+            for (const char of sql.table(params.index).compile(db).sql){
+                hash = BigInt.asUintN(64, (hash ^ BigInt(char.codePointAt(0) ?? 0)) * 1099511628211n);
+            }
+            const ginIndex = `search_${hash.toString(16)}`;
+            await sql`CREATE INDEX IF NOT EXISTS ${sql.id(ginIndex)} ON ${sql.table(params.index)} USING GIN(search_vector)`.execute(db);
+        },
+        async dropIndex (db, { index }) {
+            assertSearchIndex(index);
+            await sql`DROP TABLE IF EXISTS ${sql.table(index)} CASCADE`.execute(db);
+        },
+        async upsertEntry (db, { index, key, fields }) {
+            assertSearchIndex(index);
+            assertSearchFields(Object.keys(fields), index);
+            const vector = sql.join(Object.values(fields).map((value)=>sql`to_tsvector('simple', ${value})`), sql` || `);
+            await sql`INSERT INTO ${sql.table(index)} (entry_key, search_vector)
+        VALUES (${key}, ${vector})
+        ON CONFLICT (entry_key) DO UPDATE SET search_vector = excluded.search_vector
+      `.execute(db);
+        },
+        async removeEntry (db, { index, key }) {
+            assertSearchIndex(index);
+            await sql`DELETE FROM ${sql.table(index)} WHERE entry_key = ${key}`.execute(db);
+        },
+        async query (db, { index, query, limit }) {
+            assertSearchIndex(index);
+            const result = await sql`
+        SELECT entry_key AS key, ts_rank(search_vector, plainto_tsquery('simple', ${query})) AS rank
+        FROM ${sql.table(index)} WHERE search_vector @@ plainto_tsquery('simple', ${query})
+        ORDER BY rank DESC, entry_key LIMIT ${limit}
+      `.execute(db);
+            return result.rows;
+        }
+    };
     kind = 'postgres';
     functions = {
         now: 'now()'

package/lib/search.d.ts

@@ -0,0 +1,4 @@
+/** Logical names stay within PostgreSQL's identifier limit without truncation. */
+export declare function assertSearchIndex(index: string): void;
+/** FTS5 reserves internal columns and its table name, case-insensitively. */
+export declare function assertSearchFields(fields: Array<string>, index: string): void;

package/lib/search.js

@@ -0,0 +1,18 @@
+/** Logical names stay within PostgreSQL's identifier limit without truncation. */ export function assertSearchIndex(index) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(index)) {
+        throw new Error(`Invalid search index name: ${JSON.stringify(index)}`);
+    }
+}
+/** FTS5 reserves internal columns and its table name, case-insensitively. */ export function assertSearchFields(fields, index) {
+    if (fields.length === 0 || fields.length > 499) {
+        throw new RangeError('Search requires 1 to 499 fields');
+    }
+    const seen = new Set();
+    for (const field of fields){
+        const normalised = field.toLowerCase();
+        if (!/^[A-Za-z_][A-Za-z0-9_]{0,62}$/.test(field) || /^(entry_key|rank|rowid)$/i.test(field) || normalised === index.toLowerCase() || seen.has(normalised)) {
+            throw new Error(`Invalid search field name: ${JSON.stringify(field)}`);
+        }
+        seen.add(normalised);
+    }
+}

package/lib/sqlite.d.ts

@@ -1,11 +1,12 @@
 import type { Expression, RawBuilder } from 'kysely';
-import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection } from './types.js';
+import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection, SearchCapability } from './types.js';
 export type SQLiteTypes = {
     Binary: Uint8Array;
     JSON: string;
     Timestamp: number;
 };
 export declare abstract class AbstractSQLiteAdapter<T extends AdapterTypes = SQLiteTypes> implements AbstractAdapter<T> {
+    search: SearchCapability | undefined;
     kind: "sqlite";
     functions: Functions;
     types: ColumnTypes;

package/lib/sqlite.js

@@ -1,5 +1,47 @@
 import { sql } from 'kysely';
+import { assertSearchFields, assertSearchIndex } from './search.js';
 export class AbstractSQLiteAdapter {
+    search = {
+        async createIndex (db, params) {
+            assertSearchIndex(params.index);
+            assertSearchFields(params.fields, params.index);
+            const columns = [
+                sql`entry_key UNINDEXED`,
+                ...params.fields.map((f)=>sql.id(f))
+            ];
+            await sql`CREATE VIRTUAL TABLE IF NOT EXISTS ${sql.table(params.index)} USING fts5(${sql.join(columns)})`.execute(db);
+        },
+        async dropIndex (db, { index }) {
+            assertSearchIndex(index);
+            await sql`DROP TABLE IF EXISTS ${sql.table(index)}`.execute(db);
+        },
+        async upsertEntry (db, { index, key, fields }) {
+            assertSearchIndex(index);
+            assertSearchFields(Object.keys(fields), index);
+            // Delete and insert share the caller's transaction for atomic replacement.
+            await sql`DELETE FROM ${sql.table(index)} WHERE entry_key = ${key}`.execute(db);
+            await sql`INSERT INTO ${sql.table(index)} (${sql.join([
+                sql.id('entry_key'),
+                ...Object.keys(fields).map((f)=>sql.id(f))
+            ])}) VALUES (${sql.join([
+                key,
+                ...Object.values(fields)
+            ])})`.execute(db);
+        },
+        async removeEntry (db, { index, key }) {
+            assertSearchIndex(index);
+            await sql`DELETE FROM ${sql.table(index)} WHERE entry_key = ${key}`.execute(db);
+        },
+        async query (db, { index, query, limit }) {
+            assertSearchIndex(index);
+            const result = await sql`
+        SELECT entry_key AS key, rank FROM ${sql.table(index)}
+        WHERE ${sql.table(index)} MATCH ${query}
+        ORDER BY rank, entry_key LIMIT ${limit}
+      `.execute(db);
+            return result.rows;
+        }
+    };
     kind = 'sqlite';
     functions = {
         now: sql`(unixepoch())`

package/lib/types.d.ts

@@ -1,4 +1,4 @@
-import type { ColumnDataType, ColumnType, Dialect, Expression, RawBuilder } from 'kysely';
+import type { ColumnDataType, ColumnType, Dialect, Expression, Kysely, RawBuilder } from 'kysely';
 export type OrderDirection = 'asc' | 'desc';
 export type ArrayPresenceMode = 'null' | 'nonNull' | 'empty' | 'nonEmpty' | 'nullOrEmpty';
 export type NullOrderingTerm = {
@@ -28,8 +28,46 @@ export type AdapterTypes = {
     JSON: unknown;
     Timestamp: unknown;
 };
+/** Keys are text, matching the owning table's referenced column. */
+export type SearchIndex = {
+    index: string;
+    table: string;
+    key: string;
+    fields: Array<string>;
+};
+export type SearchEntry = {
+    index: string;
+    key: string;
+    fields: Record<string, string>;
+};
+export type SearchQuery = {
+    index: string;
+    query: string;
+    limit: number;
+};
+export type SearchHit = {
+    key: string;
+    rank: number;
+};
+/**
+ * Logical table names follow the supplied database's prefix rules.
+ * Query syntax and rank scales are dialect-specific. No method opens a transaction.
+ */
+export type SearchCapability = {
+    createIndex<Database>(db: Kysely<Database>, params: SearchIndex): Promise<void>;
+    dropIndex<Database>(db: Kysely<Database>, params: {
+        index: string;
+    }): Promise<void>;
+    upsertEntry<Database>(db: Kysely<Database>, params: SearchEntry): Promise<void>;
+    removeEntry<Database>(db: Kysely<Database>, params: {
+        index: string;
+        key: string;
+    }): Promise<void>;
+    query<Database>(db: Kysely<Database>, params: SearchQuery): Promise<Array<SearchHit>>;
+};
 export type AbstractAdapter<T extends AdapterTypes = AdapterTypes> = {
     kind: 'sqlite' | 'postgres';
+    search?: SearchCapability;
     functions: Functions;
     types: ColumnTypes;
     encodeBinary(value: Uint8Array): T['Binary'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hozon/adapter",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Database adapter interfaces and dialect behavior for Hozon",
   "repository": {
     "type": "git",
@@ -17,11 +17,11 @@
     "lib/*"
   ],
   "dependencies": {
-    "kysely": "^0.29.6"
+    "kysely": "^0.29.7"
   },
   "devDependencies": {
-    "del-cli": "^7.0.0",
-    "vitest": "5.0.3"
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.5"
   },
   "engines": {
     "node": ">=24"