@hozon/adapter 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Paul Le Cam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,17 @@
-# Temporary Holding Version
+# @hozon/adapter
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Shared adapter contract and dialect helpers for Hozon's SQLite and PostgreSQL drivers.
+
+```sh
+pnpm add @hozon/adapter
+```
+
+Import `Adapter` when defining a driver contract:
+
+```ts
+import type { Adapter } from '@hozon/adapter'
+
+type DriverContract = Adapter
+```
+
+See the [adapter reference](../../docs/reference/adapter.md).

package/lib/index.d.ts

@@ -0,0 +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, SearchCapability, SearchEntry, SearchHit, SearchIndex, SearchQuery, UpdatedAtColumn, } from './types.js';

package/lib/index.js

@@ -0,0 +1,2 @@
+export { AbstractPostgresAdapter } from './postgres.js';
+export { AbstractSQLiteAdapter } from './sqlite.js';

package/lib/postgres.d.ts

@@ -0,0 +1,24 @@
+import type { Expression, RawBuilder } from 'kysely';
+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;
+    encodeBinary(value: Uint8Array): Uint8Array<ArrayBufferLike>;
+    encodeJSON(value: unknown): unknown;
+    encodeTimestamp(value: Date): string;
+    decodeTimestamp(value: string): Date;
+    coerceFilterValue(value: unknown): unknown;
+    numericCast(expression: Expression<unknown>): Expression<number>;
+    nullOrdering(_expression: Expression<unknown>, _direction: OrderDirection): NullOrderingTerm;
+    containsPredicate(expression: Expression<unknown>, pattern: string): RawBuilder<boolean>;
+    arrayIncludesAllPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayIncludesAnyPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayPresencePredicate(expression: Expression<unknown>, mode: ArrayPresenceMode): RawBuilder<boolean>;
+}

package/lib/postgres.js

@@ -0,0 +1,131 @@
+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()'
+    };
+    types = {
+        bigint: 'bigint',
+        boolean: 'boolean',
+        double: 'double precision',
+        binary: 'bytea',
+        json: 'jsonb',
+        serial: 'serial',
+        text: 'text',
+        // Use 3 digits for timestamps to have millisecond precision, same as JS dates
+        timestamp: 'timestamptz(3)',
+        uuid: 'uuid'
+    };
+    encodeBinary(value) {
+        return value;
+    }
+    encodeJSON(value) {
+        return value;
+    }
+    encodeTimestamp(value) {
+        return value.toISOString();
+    }
+    decodeTimestamp(value) {
+        return new Date(value);
+    }
+    coerceFilterValue(value) {
+        if (typeof value === 'boolean') {
+            return value ? 'true' : 'false';
+        }
+        return value;
+    }
+    numericCast(expression) {
+        return sql`(${expression})::double precision`;
+    }
+    nullOrdering(_expression, _direction) {
+        // Postgres applies SQL-standard null position natively (NULLS LAST on asc, NULLS
+        // FIRST on desc) via the dialect's own clause on the field's order-by item.
+        return {
+            kind: 'native'
+        };
+    }
+    containsPredicate(expression, pattern) {
+        return sql`${expression} ILIKE ${pattern} ESCAPE '\\'`;
+    }
+    arrayIncludesAllPredicate(expression, values) {
+        // Native jsonb containment: works for string and numeric elements alike. NULL node
+        // coalesces to an empty array, which is a subset only of another empty set.
+        // Cast via ::text::jsonb, not a direct ::jsonb: postgres.js infers the parameter's
+        // wire type from a trailing ::jsonb cast and re-encodes the JS string as a jsonb
+        // *string scalar* instead of sending it as text for the server to parse, so a
+        // direct ::jsonb cast silently never matches. The ::text hop forces text encoding.
+        // Duplicates are ignored and an empty list is vacuously true (every array, NULL
+        // included, contains the empty set) — identical on every backend.
+        const distinct = Array.from(new Set(values));
+        if (distinct.length === 0) return sql`1 = 1`;
+        return sql`COALESCE(${expression}, '[]'::jsonb) @> ${JSON.stringify(distinct)}::text::jsonb`;
+    }
+    arrayIncludesAnyPredicate(expression, values) {
+        // An empty list matches nothing; never emit `IN ()`, which Postgres rejects.
+        if (values.length === 0) return sql`1 = 0`;
+        // Elements, not `?|`, so numeric arrays are covered too (`?|` only matches string keys).
+        return sql`EXISTS (SELECT 1 FROM jsonb_array_elements_text(COALESCE(${expression}, '[]'::jsonb)) AS _t WHERE _t IN (${sql.join(values.map((v)=>sql`${v}`))}))`;
+    }
+    arrayPresencePredicate(expression, mode) {
+        // null/nonNull/empty/nonEmpty must see the true NULL, so the node is never coalesced
+        // there — jsonb_array_length(NULL) is NULL, and NULL > 0 is not-true (excludes it).
+        switch(mode){
+            case 'null':
+                return sql`${expression} IS NULL`;
+            case 'nonNull':
+                return sql`${expression} IS NOT NULL`;
+            case 'empty':
+                return sql`jsonb_array_length(${expression}) = 0`;
+            case 'nonEmpty':
+                return sql`jsonb_array_length(${expression}) > 0`;
+            case 'nullOrEmpty':
+                return sql`COALESCE(jsonb_array_length(${expression}), 0) = 0`;
+            default:
+                throw new Error(`Invalid array presence mode: ${mode}`);
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import type { Expression, RawBuilder } from 'kysely';
+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;
+    encodeBinary(value: Uint8Array): Uint8Array<ArrayBufferLike>;
+    encodeJSON(value: unknown): string;
+    encodeTimestamp(value: Date): number;
+    decodeTimestamp(value: number): Date;
+    coerceFilterValue(value: unknown): unknown;
+    numericCast(expression: Expression<unknown>): Expression<number>;
+    nullOrdering(expression: Expression<unknown>, direction: OrderDirection): NullOrderingTerm;
+    containsPredicate(expression: Expression<unknown>, pattern: string): RawBuilder<boolean>;
+    arrayIncludesAllPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayIncludesAnyPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayPresencePredicate(expression: Expression<unknown>, mode: ArrayPresenceMode): RawBuilder<boolean>;
+}

package/lib/sqlite.js

@@ -0,0 +1,129 @@
+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())`
+    };
+    types = {
+        bigint: 'integer',
+        boolean: 'integer',
+        double: 'real',
+        binary: 'blob',
+        json: 'jsonb',
+        serial: 'integer',
+        text: 'text',
+        timestamp: 'integer',
+        uuid: 'text'
+    };
+    encodeBinary(value) {
+        return value;
+    }
+    encodeJSON(value) {
+        return JSON.stringify(value);
+    }
+    encodeTimestamp(value) {
+        // SQLite timestamps are stored in seconds
+        return Math.floor(value.getTime() / 1000);
+    }
+    decodeTimestamp(value) {
+        // SQLite timestamps are stored in seconds
+        return new Date(value * 1000);
+    }
+    coerceFilterValue(value) {
+        if (typeof value === 'boolean') {
+            return value ? 1 : 0;
+        }
+        return value;
+    }
+    numericCast(expression) {
+        return sql`CAST(${expression} AS REAL)`;
+    }
+    nullOrdering(expression, direction) {
+        // SQLite has no NULLS LAST/FIRST clause, so prepend an ascending rank column that
+        // buckets nulls last on ascending (rank 1 > 0) and first on descending (rank 0 < 1).
+        const nullRank = direction === 'asc' ? 1 : 0;
+        const valueRank = direction === 'asc' ? 0 : 1;
+        return {
+            kind: 'lead',
+            expression: sql`CASE WHEN ${expression} IS NULL THEN ${sql.lit(nullRank)} ELSE ${sql.lit(valueRank)} END`
+        };
+    }
+    containsPredicate(expression, pattern) {
+        // SQLite's LIKE is already ASCII case-insensitive by default.
+        return sql`${expression} LIKE ${pattern} ESCAPE '\\'`;
+    }
+    arrayIncludesAllPredicate(expression, values) {
+        // Duplicates are ignored (the count compares against the distinct set size) and an
+        // empty list is vacuously true — identical on every backend.
+        const distinct = Array.from(new Set(values));
+        if (distinct.length === 0) return sql`1 = 1`;
+        // NULL/absent node -> json_each yields zero rows -> COUNT(DISTINCT value) = 0, never
+        // equal to a positive set size.
+        return sql`(SELECT COUNT(DISTINCT value) FROM json_each(COALESCE(${expression}, '[]')) WHERE value IN (${sql.join(distinct.map((v)=>sql`${v}`))})) = ${distinct.length}`;
+    }
+    arrayIncludesAnyPredicate(expression, values) {
+        // An empty list matches nothing; never emit `IN ()` (portable with Postgres).
+        if (values.length === 0) return sql`1 = 0`;
+        return sql`EXISTS (SELECT 1 FROM json_each(COALESCE(${expression}, '[]')) WHERE value IN (${sql.join(values.map((v)=>sql`${v}`))}))`;
+    }
+    arrayPresencePredicate(expression, mode) {
+        // null/nonNull/empty/nonEmpty must see the true NULL, so the node is never coalesced
+        // there — json_array_length(NULL) is NULL, and NULL > 0 is not-true (excludes it).
+        switch(mode){
+            case 'null':
+                return sql`${expression} IS NULL`;
+            case 'nonNull':
+                return sql`${expression} IS NOT NULL`;
+            case 'empty':
+                return sql`json_array_length(${expression}) = 0`;
+            case 'nonEmpty':
+                return sql`json_array_length(${expression}) > 0`;
+            case 'nullOrEmpty':
+                return sql`COALESCE(json_array_length(${expression}), 0) = 0`;
+            default:
+                throw new Error(`Invalid array presence mode: ${mode}`);
+        }
+    }
+}

package/lib/types.d.ts

@@ -0,0 +1,89 @@
+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 = {
+    kind: 'lead';
+    expression: Expression<number>;
+} | {
+    kind: 'native';
+};
+export type CreatedAtColumn = ColumnType<number, number | undefined, never>;
+export type UpdatedAtColumn = ColumnType<number, number | undefined, number | undefined>;
+export type ColumnTypes = {
+    bigint: ColumnDataType;
+    binary: ColumnDataType;
+    boolean: ColumnDataType;
+    double: ColumnDataType;
+    json: ColumnDataType;
+    serial: ColumnDataType;
+    text: ColumnDataType;
+    timestamp: ColumnDataType;
+    uuid: ColumnDataType;
+};
+export type Functions = {
+    now: string | RawBuilder<string>;
+};
+export type AdapterTypes = {
+    Binary: unknown;
+    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'];
+    encodeJSON(value: unknown): T['JSON'];
+    encodeTimestamp(value: Date): T['Timestamp'];
+    decodeTimestamp(value: T['Timestamp']): Date;
+    coerceFilterValue(value: unknown): unknown;
+    numericCast(expression: Expression<unknown>): Expression<number>;
+    nullOrdering(expression: Expression<unknown>, direction: OrderDirection): NullOrderingTerm;
+    containsPredicate(expression: Expression<unknown>, pattern: string): RawBuilder<boolean>;
+    arrayIncludesAllPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayIncludesAnyPredicate(expression: Expression<unknown>, values: Array<unknown>): RawBuilder<boolean>;
+    arrayPresencePredicate(expression: Expression<unknown>, mode: ArrayPresenceMode): RawBuilder<boolean>;
+    prepare?(): Promise<void>;
+    close?(): Promise<void>;
+};
+export type Adapter<T extends AdapterTypes = AdapterTypes> = AbstractAdapter<T> & {
+    dialect: Dialect;
+};

package/lib/types.js

@@ -0,0 +1 @@
+export { };

package/package.json

@@ -1,6 +1,42 @@
 {
   "name": "@hozon/adapter",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.2.0",
+  "description": "Database adapter interfaces and dialect behavior for Hozon",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TairuFramework/hozon.git",
+    "directory": "packages/adapter"
+  },
+  "license": "MIT",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": "./lib/index.js"
+  },
+  "files": [
+    "lib/*"
+  ],
+  "dependencies": {
+    "kysely": "^0.29.7"
+  },
+  "devDependencies": {
+    "del-cli": "^8.0.1",
+    "vitest": "5.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "build:clean": "del-cli lib",
+    "build:js": "del-cli \"lib/**/*.js\" && swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
+    "build:types": "del-cli \"lib/**/*.d.ts\" \"lib/**/*.d.ts.map\" && tsc --emitDeclarationOnly --skipLibCheck",
+    "build:types:ci": "tsc --emitDeclarationOnly --skipLibCheck --declarationMap false",
+    "test": "pnpm run test:types && pnpm run test:unit",
+    "test:types": "tsc --noEmit --skipLibCheck -p tsconfig.test.json",
+    "test:unit": "vitest run"
+  }
 }