@statewalker/db-api 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mikhail Kotelnikov
+
+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

@@ -0,0 +1,29 @@
+# @statewalker/db-api
+
+Minimal database client interface — query, execute, transaction primitives — consumed by every `@statewalker/db-*` driver.
+
+## Installation
+
+```sh
+pnpm add @statewalker/db-api
+```
+
+## Usage
+
+```ts
+import type { DbClient } from "@statewalker/db-api";
+
+async function listUsers(db: DbClient) {
+  return db.query("SELECT id, name FROM users");
+}
+```
+
+## API
+
+- `DbClient` — driver-agnostic interface: `query`, `execute`, `transaction`.
+- `Row`, `QueryResult` — result-shape types returned by drivers.
+
+## Related
+
+- `@statewalker/db-duckdb-browser` / `@statewalker/db-duckdb-node` — DuckDB drivers.
+- `@statewalker/db-sqlite-browser` / `@statewalker/db-sqlite-node` — libSQL/SQLite drivers.

package/dist/index.d.mts

@@ -0,0 +1,27 @@
+//#region src/db.d.ts
+/** A plain record returned by queries when no specific type is provided. */
+type DbEntry = Record<string, unknown>;
+/** Minimal database interface — implementation-agnostic. */
+type Db = {
+  /** Execute a SQL query and return rows as typed objects. */
+  query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]>;
+  /** Execute a SQL statement that returns no rows (DDL / DML). */
+  exec(sql: string): Promise<void>;
+  /**
+   * Flush committed writes to durable storage. For backends that buffer (e.g.
+   * DuckDB-WASM over OPFS, which only writes its file on CHECKPOINT) this makes
+   * prior writes survive an abrupt teardown such as a page reload. Optional:
+   * in-memory or auto-syncing backends omit it.
+   */
+  flush?(): Promise<void>;
+  /** Release all resources held by this database. */
+  close(): Promise<void>;
+};
+/** Options accepted by every `newXxxDuckDb` factory. */
+type DbOptions = {
+  /** File path (node) or OPFS path (browser). Omit for in-memory. */
+  path?: string;
+};
+//#endregion
+export type { Db, DbEntry, DbOptions };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/db.ts"],"mappings":";;KACY,UAAU;;KAGV;;EAEV,MAAM,IAAI,SAAS,aAAa,qBAAqB,QAAQ;;EAE7D,KAAK,cAAc;;;;;;;EAOnB,UAAU;;EAEV,SAAS;;;KAIC;;EAEV"}

package/dist/index.mjs

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

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@statewalker/db-api",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "Minimal database client interface: query, execute, transaction primitives consumed by every @statewalker/db-* driver.",
+  "homepage": "https://github.com/statewalker/statewalker-db",
+  "author": {
+    "name": "Mikhail Kotelnikov",
+    "email": "mikhail.kotelnikov@gmail.com"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/statewalker/statewalker-db.git"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "rimraf": "^6.1.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  },
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf dist",
+    "lint": "biome check --write .",
+    "format": "biome format --write ."
+  }
+}

package/src/db.ts

@@ -0,0 +1,25 @@
+/** A plain record returned by queries when no specific type is provided. */
+export type DbEntry = Record<string, unknown>;
+
+/** Minimal database interface — implementation-agnostic. */
+export type Db = {
+  /** Execute a SQL query and return rows as typed objects. */
+  query<T = DbEntry>(sql: string, params?: unknown[]): Promise<T[]>;
+  /** Execute a SQL statement that returns no rows (DDL / DML). */
+  exec(sql: string): Promise<void>;
+  /**
+   * Flush committed writes to durable storage. For backends that buffer (e.g.
+   * DuckDB-WASM over OPFS, which only writes its file on CHECKPOINT) this makes
+   * prior writes survive an abrupt teardown such as a page reload. Optional:
+   * in-memory or auto-syncing backends omit it.
+   */
+  flush?(): Promise<void>;
+  /** Release all resources held by this database. */
+  close(): Promise<void>;
+};
+
+/** Options accepted by every `newXxxDuckDb` factory. */
+export type DbOptions = {
+  /** File path (node) or OPFS path (browser). Omit for in-memory. */
+  path?: string;
+};

package/src/index.ts

@@ -0,0 +1 @@
+export type { Db, DbEntry, DbOptions } from "./db.js";