@statewalker/db-pglite 0.1.1 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -19,6 +19,10 @@ pnpm add @statewalker/db-pglite @electric-sql/pglite
19
19
  pnpm add @electric-sql/pglite-pgvector # only for the pgvector example below
20
20
  ```
21
21
 
22
+ `@electric-sql/pglite` (`^0.5.15`) is a peer dependency: install it yourself, so the driver and
23
+ the extensions you pass share one PGlite. Pick the PGlite version your extensions are built for
24
+ (`@electric-sql/pglite-pgvector@0.0.16` needs PGlite `0.5.15`, `0.0.17` needs `0.5.16`).
25
+
22
26
  | Import | Gives | Environment |
23
27
  | --- | --- | --- |
24
28
  | `@statewalker/db-pglite` | `newPgliteDb`; types `PgliteDbOptions`, `Db`, `DbEntry` | Node.js, browser |
@@ -46,9 +50,18 @@ const rows = await db.query("SELECT $1::int + 1 AS n", [41]);
46
50
  `CREATE EXTENSION`; do that after opening.
47
51
  - **No transactions helper.** `inTransaction` from `@statewalker/db-sqlite` is SQLite-only and
48
52
  rejects this Db. Postgres runs `BEGIN ... COMMIT` as ordinary SQL inside one `exec`.
49
- - **After `close()`** every call rejects with `db-pglite: the database is closed`; a second
50
- `close()` does nothing.
51
- - **Dependencies:** `@electric-sql/pglite` (the engine), `@statewalker/db-api` (types).
53
+ - **One call at a time.** The `Db` is built by `newSerialisedDb` from `@statewalker/db-sqlite`
54
+ (the lifecycle every driver shares): calls run in call order; `close()` waits for the calls
55
+ made before it, then closes PGlite; a call made once `close()` has started rejects with
56
+ `db-pglite: the database is closed`; a second `close()` is a no-op.
57
+ - **Values are PGlite's**, with integers as the `Db` contract asks (`number` within
58
+ ±(2^53 - 1), `bigint` beyond): BYTEA is a `Uint8Array`, DATE and TIMESTAMP(TZ) a `Date`, and
59
+ NUMERIC/DECIMAL its exact decimal string (`"1.25"`), which PGlite returns to keep every digit;
60
+ convert it with `Number(value)` where a double is enough. The conformance suite declares its
61
+ BLOB column as `BYTEA` here (`blobType`).
62
+ - **Dependencies:** `@statewalker/db-api` (types), `@statewalker/db-sqlite` (`newSerialisedDb`,
63
+ the shared lifecycle wrapper; no SQLite engine comes with it); peer `@electric-sql/pglite`
64
+ (the engine, provided by the caller).
52
65
 
53
66
  ## License
54
67
 
package/dist/index.d.mts CHANGED
@@ -6,7 +6,11 @@ type PgliteDbOptions = {
6
6
  /** PGlite extensions to load, e.g. `{ vector }` from `@electric-sql/pglite-pgvector`. */
7
7
  extensions?: Record<string, unknown>;
8
8
  };
9
- /** Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. */
9
+ /**
10
+ * Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. Calls run one at a time, in
11
+ * call order; `close()` waits for them, then closes PGlite; later calls reject with
12
+ * `db-pglite: the database is closed`.
13
+ */
10
14
  export declare function newPgliteDb(options?: PgliteDbOptions): Promise<Db$1>;
11
15
  //#endregion
12
16
  export type { Db, DbEntry, PgliteDbOptions };
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":["Db"],"sources":["../src/pglite-db.ts"],"mappings":";;KAGY;;EAEV;;EAEA,aAAa;;;wBAIO,YAAY,UAAU,kBAAkB,QAAQA"}
1
+ {"version":3,"file":"index.d.mts","names":["Db"],"sources":["../src/pglite-db.ts"],"mappings":";;KAIY;;EAEV;;EAEA,aAAa;;;;;;;wBAQO,YAAY,UAAU,kBAAkB,QAAQA"}
package/dist/index.mjs CHANGED
@@ -1,30 +1,23 @@
1
1
  import { PGlite } from "@electric-sql/pglite";
2
+ import { newSerialisedDb } from "@statewalker/db-sqlite";
2
3
  //#region src/pglite-db.ts
3
- /** Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. */
4
+ /**
5
+ * Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. Calls run one at a time, in
6
+ * call order; `close()` waits for them, then closes PGlite; later calls reject with
7
+ * `db-pglite: the database is closed`.
8
+ */
4
9
  async function newPgliteDb(options) {
5
10
  const pg = await PGlite.create({
6
11
  dataDir: options?.path,
7
12
  extensions: options?.extensions
8
13
  });
9
- let closed = false;
10
- const live = () => {
11
- if (closed) throw new Error("db-pglite: the database is closed");
12
- };
13
- return {
14
- async query(sql, params) {
15
- live();
16
- return (await pg.query(sql, params ?? [])).rows;
17
- },
18
- async exec(sql) {
19
- live();
14
+ return newSerialisedDb({
15
+ query: async (sql, params) => (await pg.query(sql, params)).rows,
16
+ exec: async (sql) => {
20
17
  await pg.exec(sql);
21
18
  },
22
- async close() {
23
- if (closed) return;
24
- closed = true;
25
- await pg.close();
26
- }
27
- };
19
+ close: () => pg.close()
20
+ }, { name: "db-pglite" });
28
21
  }
29
22
  //#endregion
30
23
  export { newPgliteDb };
@@ -1 +1 @@
1
- {"version":3,"file":"index.mjs","names":[],"sources":["../src/pglite-db.ts"],"sourcesContent":["import { type Extensions, PGlite } from \"@electric-sql/pglite\";\nimport type { Db, DbEntry } from \"@statewalker/db-api\";\n\nexport type PgliteDbOptions = {\n /** PGlite data directory: a folder on Node.js, `idb://<name>` in a browser. Omit for in-memory. */\n path?: string;\n /** PGlite extensions to load, e.g. `{ vector }` from `@electric-sql/pglite-pgvector`. */\n extensions?: Record<string, unknown>;\n};\n\n/** Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. */\nexport async function newPgliteDb(options?: PgliteDbOptions): Promise<Db> {\n const pg = await PGlite.create({\n dataDir: options?.path,\n extensions: options?.extensions as Extensions | undefined,\n });\n let closed = false;\n const live = () => {\n if (closed) throw new Error(\"db-pglite: the database is closed\");\n };\n return {\n async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {\n live();\n return (await pg.query<T>(sql, params ?? [])).rows;\n },\n async exec(sql: string): Promise<void> {\n live();\n await pg.exec(sql);\n },\n async close(): Promise<void> {\n if (closed) return;\n closed = true;\n await pg.close();\n },\n };\n}\n"],"mappings":";;;AAWA,eAAsB,YAAY,SAAwC;CACxE,MAAM,KAAK,MAAM,OAAO,OAAO;EAC7B,SAAS,SAAS;EAClB,YAAY,SAAS;CACvB,CAAC;CACD,IAAI,SAAS;CACb,MAAM,aAAa;EACjB,IAAI,QAAQ,MAAM,IAAI,MAAM,mCAAmC;CACjE;CACA,OAAO;EACL,MAAM,MAAmB,KAAa,QAAkC;GACtE,KAAK;GACL,QAAQ,MAAM,GAAG,MAAS,KAAK,UAAU,CAAC,CAAC,EAAA,CAAG;EAChD;EACA,MAAM,KAAK,KAA4B;GACrC,KAAK;GACL,MAAM,GAAG,KAAK,GAAG;EACnB;EACA,MAAM,QAAuB;GAC3B,IAAI,QAAQ;GACZ,SAAS;GACT,MAAM,GAAG,MAAM;EACjB;CACF;AACF"}
1
+ {"version":3,"file":"index.mjs","names":[],"sources":["../src/pglite-db.ts"],"sourcesContent":["import { type Extensions, PGlite } from \"@electric-sql/pglite\";\nimport type { Db } from \"@statewalker/db-api\";\nimport { newSerialisedDb } from \"@statewalker/db-sqlite\";\n\nexport type PgliteDbOptions = {\n /** PGlite data directory: a folder on Node.js, `idb://<name>` in a browser. Omit for in-memory. */\n path?: string;\n /** PGlite extensions to load, e.g. `{ vector }` from `@electric-sql/pglite-pgvector`. */\n extensions?: Record<string, unknown>;\n};\n\n/**\n * Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. Calls run one at a time, in\n * call order; `close()` waits for them, then closes PGlite; later calls reject with\n * `db-pglite: the database is closed`.\n */\nexport async function newPgliteDb(options?: PgliteDbOptions): Promise<Db> {\n const pg = await PGlite.create({\n dataDir: options?.path,\n extensions: options?.extensions as Extensions | undefined,\n });\n return newSerialisedDb(\n {\n query: async (sql, params) => (await pg.query<Record<string, unknown>>(sql, params)).rows,\n exec: async (sql) => {\n await pg.exec(sql);\n },\n close: () => pg.close(),\n },\n { name: \"db-pglite\" },\n );\n}\n"],"mappings":";;;;;;;;AAgBA,eAAsB,YAAY,SAAwC;CACxE,MAAM,KAAK,MAAM,OAAO,OAAO;EAC7B,SAAS,SAAS;EAClB,YAAY,SAAS;CACvB,CAAC;CACD,OAAO,gBACL;EACE,OAAO,OAAO,KAAK,YAAY,MAAM,GAAG,MAA+B,KAAK,MAAM,EAAA,CAAG;EACrF,MAAM,OAAO,QAAQ;GACnB,MAAM,GAAG,KAAK,GAAG;EACnB;EACA,aAAa,GAAG,MAAM;CACxB,GACA,EAAE,MAAM,YAAY,CACtB;AACF"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@statewalker/db-pglite",
3
- "version": "0.1.1",
3
+ "version": "0.3.0",
4
4
  "private": false,
5
5
  "type": "module",
6
6
  "description": "PGlite (Postgres in WASM) driver for @statewalker/db-api, for Node.js and the browser.",
@@ -22,19 +22,25 @@
22
22
  ".": {
23
23
  "source": "./src/index.ts",
24
24
  "types": "./dist/index.d.mts",
25
- "import": "./dist/index.mjs"
25
+ "import": "./dist/index.mjs",
26
+ "default": "./dist/index.mjs"
26
27
  }
27
28
  },
28
29
  "files": [
29
30
  "dist",
30
- "src"
31
+ "src",
32
+ "!src/**/*.test.ts"
31
33
  ],
32
34
  "dependencies": {
33
- "@electric-sql/pglite": "^0.5.8",
34
- "@statewalker/db-api": "^0.1.5"
35
+ "@statewalker/db-api": "^0.1.7",
36
+ "@statewalker/db-sqlite": "^0.1.3"
37
+ },
38
+ "peerDependencies": {
39
+ "@electric-sql/pglite": "^0.5.15"
35
40
  },
36
41
  "devDependencies": {
37
- "@electric-sql/pglite-pgvector": "^0.0.16",
42
+ "@electric-sql/pglite": "^0.5.16",
43
+ "@electric-sql/pglite-pgvector": "^0.0.17",
38
44
  "@types/node": "^26.6.4",
39
45
  "rimraf": "^6.1.3",
40
46
  "tsdown": "^0.23.0",
package/src/pglite-db.ts CHANGED
@@ -1,5 +1,6 @@
1
1
  import { type Extensions, PGlite } from "@electric-sql/pglite";
2
- import type { Db, DbEntry } from "@statewalker/db-api";
2
+ import type { Db } from "@statewalker/db-api";
3
+ import { newSerialisedDb } from "@statewalker/db-sqlite";
3
4
 
4
5
  export type PgliteDbOptions = {
5
6
  /** PGlite data directory: a folder on Node.js, `idb://<name>` in a browser. Omit for in-memory. */
@@ -8,29 +9,24 @@ export type PgliteDbOptions = {
8
9
  extensions?: Record<string, unknown>;
9
10
  };
10
11
 
11
- /** Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. */
12
+ /**
13
+ * Create a {@link Db} on PGlite. Use `$1`, `$2`, ... placeholders. Calls run one at a time, in
14
+ * call order; `close()` waits for them, then closes PGlite; later calls reject with
15
+ * `db-pglite: the database is closed`.
16
+ */
12
17
  export async function newPgliteDb(options?: PgliteDbOptions): Promise<Db> {
13
18
  const pg = await PGlite.create({
14
19
  dataDir: options?.path,
15
20
  extensions: options?.extensions as Extensions | undefined,
16
21
  });
17
- let closed = false;
18
- const live = () => {
19
- if (closed) throw new Error("db-pglite: the database is closed");
20
- };
21
- return {
22
- async query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]> {
23
- live();
24
- return (await pg.query<T>(sql, params ?? [])).rows;
22
+ return newSerialisedDb(
23
+ {
24
+ query: async (sql, params) => (await pg.query<Record<string, unknown>>(sql, params)).rows,
25
+ exec: async (sql) => {
26
+ await pg.exec(sql);
27
+ },
28
+ close: () => pg.close(),
25
29
  },
26
- async exec(sql: string): Promise<void> {
27
- live();
28
- await pg.exec(sql);
29
- },
30
- async close(): Promise<void> {
31
- if (closed) return;
32
- closed = true;
33
- await pg.close();
34
- },
35
- };
30
+ { name: "db-pglite" },
31
+ );
36
32
  }
@@ -1,20 +0,0 @@
1
- import { vector } from "@electric-sql/pglite-pgvector";
2
- import { runDbConformance } from "@statewalker/db-tests";
3
- import { describe, expect, it } from "vitest";
4
- import { newPgliteDb } from "./pglite-db.js";
5
-
6
- runDbConformance((options) => newPgliteDb(options), { placeholder: "$1" });
7
-
8
- describe("newPgliteDb", () => {
9
- it("loads the extensions it is given (pgvector, as indexer-pglite needs)", async () => {
10
- const db = await newPgliteDb({ extensions: { vector } });
11
- try {
12
- await db.exec("CREATE EXTENSION IF NOT EXISTS vector; CREATE TABLE v (e vector(3))");
13
- await db.query("INSERT INTO v VALUES ($1::vector)", ["[1,2,3]"]);
14
- const rows = await db.query<{ d: number }>("SELECT e <-> '[1,2,4]'::vector AS d FROM v");
15
- expect(rows[0]?.d).toBeCloseTo(1);
16
- } finally {
17
- await db.close();
18
- }
19
- });
20
- });