@omniojs/idx-postgresql.node 0.0.0-stage → 0.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026-present, omnio-project
+
+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,21 @@
-# Temporary Holding Version
+# @omniojs/idx-postgresql.node
 
-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.
+PostgreSQL による Omnio.js 用の `IObjectIndex` 実装です。
+
+ベクトル検索には pgvector を使います。接続先のデータベースで pgvector 拡張を利用できるようにしてください。マイグレーション時に `CREATE EXTENSION IF NOT EXISTS vector` を実行します。
+
+[Document](https://omnio-project.github.io/omnio-js/)
+
+## テスト
+
+ローカルで `mise run test` を実行すると、Docker Compose で pgvector 入りの PostgreSQL 17 を起動し、テスト終了後に停止します。Docker が必要です。
+
+PostgreSQL を起動したままテストを繰り返す場合は、次のコマンドを使います。
+
+```sh
+mise run db:start
+mise run test:server
+mise run db:stop
+```
+
+`DATABASE_URL` を指定した場合は、そのサーバーを使ってローカルのコンテナを起動しません。

package/dist/index.d.ts

@@ -0,0 +1,44 @@
+import { Migration, Migration as Migration$1, MigrationProvider, Migrator } from "kysely/migration";
+import { PgVectorObjectIndex, SqlIndexBackend, SqlIndexDatabase as PostgresqlDatabase, SqlMigrationProvider, SqlObjectRow as ObjectRow, SqlObjectTagRow as ObjectTagRow, cosineSimilarity, decodeEmbedding, encodeEmbedding, l2Distance, scoreVector } from "@omniojs/idx-sql";
+//#region ../src/migrations.d.ts
+/**
+ * 適用するマイグレーションの一覧です。キー名の辞書順で実行します。
+ */
+export declare const MIGRATIONS: Record<string, Migration$1>;
+/**
+ * PostgreSQL 用のマイグレーション提供器です。
+ */
+export declare class PostgresqlMigrationProvider extends SqlMigrationProvider {
+  /**
+   * マイグレーションの一覧を設定します。
+   */
+  constructor();
+}
+//#endregion
+//#region ../src/postgresql-index.d.ts
+/**
+ * `PostgresqlIndex` のオプションです。
+ */
+type PostgresqlIndexOptions = {
+  /** PostgreSQL への接続文字列です。 */
+  readonly connectionString: string;
+  /** コネクションプールの最大接続数です。既定値は 10 です。 */
+  readonly maxConnections?: number | undefined;
+};
+/**
+ * PostgreSQL による `IObjectIndex` の実装です。
+ */
+export declare class PostgresqlIndex extends PgVectorObjectIndex {
+  #private;
+  protected override readonly fullTextOperator: "ILIKE";
+  /**
+   * @param options 接続文字列などの設定です。
+   */
+  constructor(options: PostgresqlIndexOptions);
+  protected override createBackend(): Promise<SqlIndexBackend>;
+  protected override createMigrationProvider(): MigrationProvider;
+  protected override toStoredSize(size: number): string;
+}
+//#endregion
+export { type Migration, Migrator, type ObjectRow, type ObjectTagRow, type PostgresqlDatabase, type PostgresqlIndexOptions, cosineSimilarity, decodeEmbedding, encodeEmbedding, l2Distance, scoreVector };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":["Migration"],"sources":["../src/migrations.ts","../src/postgresql-index.ts"],"mappings":";;;;;;qBAMa,YAAY,eAAeA;;;;qBAQ3B,oCAAoC;;;;EAI/C;;;;;;;KCLU;;WAED;;WAGA;;;;;qBA6BE,wBAAwB;;8BACP;;;;EAS5B,YAAmB,SAAS;qBAQT,iBAAiB,QAAQ;qBAyBzB,2BAA2B;qBAI3B,aAAa"}

package/dist/index.js

@@ -0,0 +1,115 @@
+import { Migrator } from "kysely/migration";
+import { PgVectorObjectIndex, SqlMigrationProvider, cosineSimilarity, createSqlMigrations, decodeEmbedding, encodeEmbedding, l2Distance, scoreVector } from "@omniojs/idx-sql";
+import { Kysely, PostgresDialect } from "kysely";
+import { Pool } from "pg";
+import * as v from "valibot";
+//#region ../src/migrations.ts
+/**
+* 適用するマイグレーションの一覧です。キー名の辞書順で実行します。
+*/
+const MIGRATIONS = createSqlMigrations({
+	sizeColumnType: "bigint",
+	embeddingColumnType: "vector"
+});
+/**
+* PostgreSQL 用のマイグレーション提供器です。
+*/
+var PostgresqlMigrationProvider = class extends SqlMigrationProvider {
+	/**
+	* マイグレーションの一覧を設定します。
+	*/
+	constructor() {
+		super(MIGRATIONS);
+	}
+};
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/checkPrivateRedeclaration.js
+function _checkPrivateRedeclaration(e, t) {
+	if (t.has(e)) throw new TypeError("Cannot initialize the same private elements twice on an object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldInitSpec.js
+function _classPrivateFieldInitSpec(e, t, a) {
+	_checkPrivateRedeclaration(e, t), t.set(e, a);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/assertClassBrand.js
+function _assertClassBrand(e, t, n) {
+	if ("function" == typeof e ? e === t : e.has(t)) return arguments.length < 3 ? t : n;
+	throw new TypeError("Private element is not present on this object");
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldSet2.js
+function _classPrivateFieldSet2(s, a, r) {
+	return s.set(_assertClassBrand(s, a), r), r;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.154.0/helpers/esm/classPrivateFieldGet2.js
+function _classPrivateFieldGet2(s, a) {
+	return s.get(_assertClassBrand(s, a));
+}
+//#endregion
+//#region ../src/postgresql-index.ts
+/**
+* `PostgresqlIndex` のコンストラクター引数を検証するスキーマです。
+*/
+const PostgresqlIndexOptionsSchema = v.object({
+	maxConnections: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+	connectionString: v.pipe(v.string(), v.minLength(1))
+});
+/**
+* 開いているコネクションプールを閉じます。
+*
+* Kysely の `destroy()` はドライバーの初期化に失敗していると接続を破棄しないため、後始末のフォールバックとして使います。
+*
+* @param pool 閉じるコネクションプールです。
+*/
+async function closePool(pool) {
+	try {
+		await pool.end();
+	} catch {}
+}
+var _connectionString = /* @__PURE__ */ new WeakMap();
+var _maxConnections = /* @__PURE__ */ new WeakMap();
+/**
+* PostgreSQL による `IObjectIndex` の実装です。
+*/
+var PostgresqlIndex = class extends PgVectorObjectIndex {
+	/**
+	* @param options 接続文字列などの設定です。
+	*/
+	constructor(options) {
+		super();
+		this.fullTextOperator = "ILIKE";
+		_classPrivateFieldInitSpec(this, _connectionString, void 0);
+		_classPrivateFieldInitSpec(this, _maxConnections, void 0);
+		const parsed = v.parse(PostgresqlIndexOptionsSchema, options);
+		_classPrivateFieldSet2(_connectionString, this, parsed.connectionString);
+		_classPrivateFieldSet2(_maxConnections, this, parsed.maxConnections);
+	}
+	createBackend() {
+		const pool = new Pool({
+			max: _classPrivateFieldGet2(_maxConnections, this),
+			connectionString: _classPrivateFieldGet2(_connectionString, this)
+		});
+		pool.on("error", () => {});
+		const kysely = new Kysely({ dialect: new PostgresDialect({ pool }) });
+		return Promise.resolve({
+			kysely,
+			dispose: async () => {
+				await kysely.destroy().catch(() => void 0);
+				await closePool(pool);
+			}
+		});
+	}
+	createMigrationProvider() {
+		return new PostgresqlMigrationProvider();
+	}
+	toStoredSize(size) {
+		return String(size);
+	}
+};
+//#endregion
+export { MIGRATIONS, Migrator, PostgresqlIndex, PostgresqlMigrationProvider, cosineSimilarity, decodeEmbedding, encodeEmbedding, l2Distance, scoreVector };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/migrations.ts","../src/postgresql-index.ts"],"sourcesContent":["import { createSqlMigrations, SqlMigrationProvider } from \"@omniojs/idx-sql\";\nimport type { Migration } from \"kysely/migration\";\n\n/**\n * 適用するマイグレーションの一覧です。キー名の辞書順で実行します。\n */\nexport const MIGRATIONS: Record<string, Migration> = createSqlMigrations({\n  sizeColumnType: \"bigint\",\n  embeddingColumnType: \"vector\",\n});\n\n/**\n * PostgreSQL 用のマイグレーション提供器です。\n */\nexport class PostgresqlMigrationProvider extends SqlMigrationProvider {\n  /**\n   * マイグレーションの一覧を設定します。\n   */\n  public constructor() {\n    super(MIGRATIONS);\n  }\n}\n","import type { SqlIndexBackend } from \"@omniojs/idx-sql\";\nimport { PgVectorObjectIndex } from \"@omniojs/idx-sql\";\nimport { Kysely, PostgresDialect } from \"kysely\";\nimport type { MigrationProvider } from \"kysely/migration\";\nimport { Pool } from \"pg\";\nimport * as v from \"valibot\";\n\nimport { PostgresqlMigrationProvider } from \"./migrations.js\";\nimport type { PostgresqlDatabase } from \"./schema.js\";\n\n/**\n * `PostgresqlIndex` のオプションです。\n */\nexport type PostgresqlIndexOptions = {\n  /** PostgreSQL への接続文字列です。 */\n  readonly connectionString: string;\n\n  /** コネクションプールの最大接続数です。既定値は 10 です。 */\n  readonly maxConnections?: number | undefined;\n};\n\n/**\n * `PostgresqlIndex` のコンストラクター引数を検証するスキーマです。\n */\nconst PostgresqlIndexOptionsSchema = v.object({\n  maxConnections: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),\n  connectionString: v.pipe(v.string(), v.minLength(1)),\n});\n\n/**\n * 開いているコネクションプールを閉じます。\n *\n * Kysely の `destroy()` はドライバーの初期化に失敗していると接続を破棄しないため、後始末のフォールバックとして使います。\n *\n * @param pool 閉じるコネクションプールです。\n */\nasync function closePool(pool: Pool): Promise<void> {\n  try {\n    await pool.end();\n  } catch {\n    // 元のエラーを優先するため、後始末の失敗は無視します。\n  }\n}\n\n/**\n * PostgreSQL による `IObjectIndex` の実装です。\n */\nexport class PostgresqlIndex extends PgVectorObjectIndex {\n  protected override readonly fullTextOperator = \"ILIKE\" as const;\n\n  readonly #connectionString: string;\n\n  readonly #maxConnections: number | undefined;\n\n  /**\n   * @param options 接続文字列などの設定です。\n   */\n  public constructor(options: PostgresqlIndexOptions) {\n    super();\n\n    const parsed = v.parse(PostgresqlIndexOptionsSchema, options);\n    this.#connectionString = parsed.connectionString;\n    this.#maxConnections = parsed.maxConnections;\n  }\n\n  protected override createBackend(): Promise<SqlIndexBackend> {\n    const pool = new Pool({\n      max: this.#maxConnections,\n      connectionString: this.#connectionString,\n    });\n\n    // 待機中のクライアントで発生したエラーはクエリーの Promise に紐付かないため、リスナーがないと未処理の error イベントでプロセスが終了します。\n    // クエリー実行中のエラーは引き続き Promise の reject として呼び出し元に伝わります。\n    pool.on(\"error\", () => {\n      // プールは影響を受けたクライアントを破棄するため、ここでは何もしません。\n    });\n\n    const kysely = new Kysely<PostgresqlDatabase>({\n      dialect: new PostgresDialect({ pool }),\n    });\n\n    return Promise.resolve({\n      kysely,\n      dispose: async () => {\n        await kysely.destroy().catch(() => undefined);\n        await closePool(pool);\n      },\n    });\n  }\n\n  protected override createMigrationProvider(): MigrationProvider {\n    return new PostgresqlMigrationProvider();\n  }\n\n  protected override toStoredSize(size: number): string {\n    return String(size);\n  }\n}\n"],"mappings":";;;;;;;;;AAMA,MAAa,aAAwC,oBAAoB;CACvE,gBAAgB;CAChB,qBAAqB;AACvB,CAAC;;;;AAKD,IAAa,8BAAb,cAAiD,qBAAqB;;;;CAIpE,cAAqB;EACnB,MAAM,UAAU;CAClB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;ACGA,MAAM,+BAA+B,EAAE,OAAO;CAC5C,gBAAgB,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,GAAG,EAAE,QAAQ,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC;CACzE,kBAAkB,EAAE,KAAK,EAAE,OAAO,GAAG,EAAE,UAAU,CAAC,CAAC;AACrD,CAAC;;;;;;;;AASD,eAAe,UAAU,MAA2B;CAClD,IAAI;EACF,MAAM,KAAK,IAAI;CACjB,QAAQ,CAER;AACF;;;;;;AAKA,IAAa,kBAAb,cAAqC,oBAAoB;;;;CAUvD,YAAmB,SAAiC;EAClD,MAAM;EAVR,KAA4B,mBAAmB;;;EAY7C,MAAM,SAAS,EAAE,MAAM,8BAA8B,OAAO;EAC5D,uBAAA,mBAAA,MAAyB,OAAO,gBAAA;EAChC,uBAAA,iBAAA,MAAuB,OAAO,cAAA;CAChC;CAEA,gBAA6D;EAC3D,MAAM,OAAO,IAAI,KAAK;GACpB,KAAA,uBAAA,iBAAK,IAAA;GACL,kBAAA,uBAAA,mBAAkB,IAAA;EACpB,CAAC;EAID,KAAK,GAAG,eAAe,CAEvB,CAAC;EAED,MAAM,SAAS,IAAI,OAA2B,EAC5C,SAAS,IAAI,gBAAgB,EAAE,KAAK,CAAC,EACvC,CAAC;EAED,OAAO,QAAQ,QAAQ;GACrB;GACA,SAAS,YAAY;IACnB,MAAM,OAAO,QAAQ,CAAC,CAAC,YAAY,KAAA,CAAS;IAC5C,MAAM,UAAU,IAAI;GACtB;EACF,CAAC;CACH;CAEA,0BAAgE;EAC9D,OAAO,IAAI,4BAA4B;CACzC;CAEA,aAAgC,MAAsB;EACpD,OAAO,OAAO,IAAI;CACpB;AACF"}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@omniojs/idx-postgresql.node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.5",
+  "description": "PostgreSQL による Omnio.js 用 ObjectIndex です。",
+  "homepage": "https://omnio-project.github.io/omnio-js/",
+  "license": "MIT",
+  "repository": {
+    "url": "https://github.com/omnio-project/omnio-js",
+    "directory": "packages/idx-postgresql.node"
+  },
+  "files": [
+    "dist",
+    "src",
+    "package.json",
+    "LICENSE",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@omniojs/core": "0.0.5",
+    "@omniojs/idx-sql": "0.0.5",
+    "asyncmux": "^0.0.12",
+    "kysely": "^0.29.7",
+    "pg": "^8.23.1",
+    "valibot": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/pg": "^8.23.1",
+    "@vitest/coverage-v8": "5.0.5",
+    "vite-plus": "1.3.0"
+  },
+  "readme": "README.md",
+  "scripts": {
+    "build": "vp -C .config pack"
+  }
 }

package/src/index.ts

@@ -0,0 +1,16 @@
+export type { Migration } from "kysely/migration";
+export { Migrator } from "kysely/migration";
+export { MIGRATIONS, PostgresqlMigrationProvider } from "./migrations.js";
+
+export type { PostgresqlIndexOptions } from "./postgresql-index.js";
+export { PostgresqlIndex } from "./postgresql-index.js";
+
+export type { ObjectRow, ObjectTagRow, PostgresqlDatabase } from "./schema.js";
+
+export {
+  l2Distance,
+  scoreVector,
+  decodeEmbedding,
+  encodeEmbedding,
+  cosineSimilarity,
+} from "./vector.js";

package/src/migrations.ts

@@ -0,0 +1,22 @@
+import { createSqlMigrations, SqlMigrationProvider } from "@omniojs/idx-sql";
+import type { Migration } from "kysely/migration";
+
+/**
+ * 適用するマイグレーションの一覧です。キー名の辞書順で実行します。
+ */
+export const MIGRATIONS: Record<string, Migration> = createSqlMigrations({
+  sizeColumnType: "bigint",
+  embeddingColumnType: "vector",
+});
+
+/**
+ * PostgreSQL 用のマイグレーション提供器です。
+ */
+export class PostgresqlMigrationProvider extends SqlMigrationProvider {
+  /**
+   * マイグレーションの一覧を設定します。
+   */
+  public constructor() {
+    super(MIGRATIONS);
+  }
+}

package/src/postgresql-index.ts

@@ -0,0 +1,98 @@
+import type { SqlIndexBackend } from "@omniojs/idx-sql";
+import { PgVectorObjectIndex } from "@omniojs/idx-sql";
+import { Kysely, PostgresDialect } from "kysely";
+import type { MigrationProvider } from "kysely/migration";
+import { Pool } from "pg";
+import * as v from "valibot";
+
+import { PostgresqlMigrationProvider } from "./migrations.js";
+import type { PostgresqlDatabase } from "./schema.js";
+
+/**
+ * `PostgresqlIndex` のオプションです。
+ */
+export type PostgresqlIndexOptions = {
+  /** PostgreSQL への接続文字列です。 */
+  readonly connectionString: string;
+
+  /** コネクションプールの最大接続数です。既定値は 10 です。 */
+  readonly maxConnections?: number | undefined;
+};
+
+/**
+ * `PostgresqlIndex` のコンストラクター引数を検証するスキーマです。
+ */
+const PostgresqlIndexOptionsSchema = v.object({
+  maxConnections: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1))),
+  connectionString: v.pipe(v.string(), v.minLength(1)),
+});
+
+/**
+ * 開いているコネクションプールを閉じます。
+ *
+ * Kysely の `destroy()` はドライバーの初期化に失敗していると接続を破棄しないため、後始末のフォールバックとして使います。
+ *
+ * @param pool 閉じるコネクションプールです。
+ */
+async function closePool(pool: Pool): Promise<void> {
+  try {
+    await pool.end();
+  } catch {
+    // 元のエラーを優先するため、後始末の失敗は無視します。
+  }
+}
+
+/**
+ * PostgreSQL による `IObjectIndex` の実装です。
+ */
+export class PostgresqlIndex extends PgVectorObjectIndex {
+  protected override readonly fullTextOperator = "ILIKE" as const;
+
+  readonly #connectionString: string;
+
+  readonly #maxConnections: number | undefined;
+
+  /**
+   * @param options 接続文字列などの設定です。
+   */
+  public constructor(options: PostgresqlIndexOptions) {
+    super();
+
+    const parsed = v.parse(PostgresqlIndexOptionsSchema, options);
+    this.#connectionString = parsed.connectionString;
+    this.#maxConnections = parsed.maxConnections;
+  }
+
+  protected override createBackend(): Promise<SqlIndexBackend> {
+    const pool = new Pool({
+      max: this.#maxConnections,
+      connectionString: this.#connectionString,
+    });
+
+    // 待機中のクライアントで発生したエラーはクエリーの Promise に紐付かないため、リスナーがないと未処理の error イベントでプロセスが終了します。
+    // クエリー実行中のエラーは引き続き Promise の reject として呼び出し元に伝わります。
+    pool.on("error", () => {
+      // プールは影響を受けたクライアントを破棄するため、ここでは何もしません。
+    });
+
+    const kysely = new Kysely<PostgresqlDatabase>({
+      dialect: new PostgresDialect({ pool }),
+    });
+
+    return Promise.resolve({
+      kysely,
+      dispose: async () => {
+        await kysely.destroy().catch(() => undefined);
+        await closePool(pool);
+      },
+    });
+  }
+
+  protected override createMigrationProvider(): MigrationProvider {
+    return new PostgresqlMigrationProvider();
+  }
+
+  protected override toStoredSize(size: number): string {
+    return String(size);
+  }
+}

package/src/schema.ts

@@ -0,0 +1,5 @@
+export type {
+  SqlObjectRow as ObjectRow,
+  SqlObjectTagRow as ObjectTagRow,
+  SqlIndexDatabase as PostgresqlDatabase,
+} from "@omniojs/idx-sql";

package/src/vector.ts

@@ -0,0 +1,8 @@
+export {
+  l2Distance,
+  scoreVector,
+  decodeEmbedding,
+  encodeEmbedding,
+  cosineSimilarity,
+  decodeEmbeddingInto,
+} from "@omniojs/idx-sql";