@hozon/adapter 0.0.0-stage → 0.1.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, 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,23 @@
+import type { Expression, RawBuilder } from 'kysely';
+import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection } from './types.js';
+export type PostgresTypes = {
+    Binary: Uint8Array;
+    JSON: unknown;
+    Timestamp: string;
+};
+export declare abstract class AbstractPostgresAdapter<T extends AdapterTypes = PostgresTypes> implements AbstractAdapter<T> {
+    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,87 @@
+import { sql } from 'kysely';
+export class AbstractPostgresAdapter {
+    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/sqlite.d.ts

@@ -0,0 +1,23 @@
+import type { Expression, RawBuilder } from 'kysely';
+import type { AbstractAdapter, AdapterTypes, ArrayPresenceMode, ColumnTypes, Functions, NullOrderingTerm, OrderDirection } from './types.js';
+export type SQLiteTypes = {
+    Binary: Uint8Array;
+    JSON: string;
+    Timestamp: number;
+};
+export declare abstract class AbstractSQLiteAdapter<T extends AdapterTypes = SQLiteTypes> implements AbstractAdapter<T> {
+    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,87 @@
+import { sql } from 'kysely';
+export class AbstractSQLiteAdapter {
+    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,51 @@
+import type { ColumnDataType, ColumnType, Dialect, Expression, 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;
+};
+export type AbstractAdapter<T extends AdapterTypes = AdapterTypes> = {
+    kind: 'sqlite' | 'postgres';
+    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.1.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.6"
+  },
+  "devDependencies": {
+    "del-cli": "^7.0.0",
+    "vitest": "5.0.3"
+  },
+  "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"
+  }
 }