@humbdb/driver-contract 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Humb contributors
+
+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,6 @@
+# @humbdb/driver-contract
+
+Engine-agnostic database adapter contracts. Concrete engine drivers implement `DatabaseAdapter`.
+
+To add a new engine, create a `packages/drivers/<engine>` package that implements these interfaces.
+See [`ARCHITECTURE.md`](../../../ARCHITECTURE.md).

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+import { ConnectionTarget, DatabaseOverview, TableMetadata, RowPage } from '@humbdb/core';
+
+/** A live, engine-specific connection to a single database. */
+interface DatabaseAdapter {
+    /** The engine identifier, e.g. "postgres". */
+    readonly engine: string;
+    /** Establish the underlying connection/pool. */
+    connect(): Promise<void>;
+    /** Tear down the connection/pool and release resources. */
+    disconnect(): Promise<void>;
+    /** Lightweight connectivity check. */
+    ping(): Promise<boolean>;
+    /** Human-readable engine name + version, e.g. "PostgreSQL 16.1", "SQLite 3.45.0". */
+    getVersion(): Promise<string>;
+    /** Introspect the overall structure (schemas and tables). */
+    getOverview(): Promise<DatabaseOverview>;
+    /** Introspect a single table's columns and metadata. */
+    getTable(schema: string, table: string): Promise<TableMetadata>;
+    /** Fetch a page of rows for a table. */
+    getRows(schema: string, table: string, page: number, pageSize: number): Promise<RowPage>;
+    /** Execute a read-only (SELECT-style) query. Implementations must reject mutations. */
+    runReadOnlyQuery(sql: string): Promise<RowPage>;
+}
+/** Creates {@link DatabaseAdapter} instances for targets a given engine supports. */
+interface AdapterFactory {
+    readonly engine: string;
+    /** Whether this factory can handle the given connection target. */
+    supports(target: ConnectionTarget): boolean;
+    /** Create (but do not yet connect) an adapter for the target. */
+    create(target: ConnectionTarget): DatabaseAdapter;
+}
+
+/** Thrown when no registered adapter supports a connection target. */
+declare class UnsupportedEngineError extends Error {
+    constructor(engine: string);
+}
+/**
+ * Thrown when a query passed to `DatabaseAdapter.runReadOnlyQuery` violates Humb's read-only
+ * policy. Engine-agnostic so `packages/server` can catch it (and return 400) without depending on
+ * any concrete engine package - every engine's query runner throws this same class.
+ */
+declare class ReadOnlyViolationError extends Error {
+    constructor(message: string);
+}
+
+/** Resolve the first factory that supports the target, or throw. */
+declare function resolveAdapter(factories: readonly AdapterFactory[], target: ConnectionTarget): DatabaseAdapter;
+
+/** A resolved, safely-bounded page request. */
+interface ResolvedPageRequest {
+    readonly page: number;
+    readonly pageSize: number;
+    readonly offset: number;
+}
+/**
+ * Clamp a requested page/pageSize into safe, non-negative bounds. Shared by every engine adapter so
+ * pagination behaves identically regardless of which database is behind it - do not reimplement
+ * this per engine.
+ */
+declare function resolvePageRequest(page: number, pageSize: number): ResolvedPageRequest;
+
+/**
+ * Assert that a SQL string is a single read-only statement. Engine-agnostic: pure text scanning,
+ * shared by every engine adapter so the heuristic behaves identically regardless of which database
+ * is behind it.
+ *
+ * Throws {@link ReadOnlyViolationError} otherwise. This is a defense-in-depth check; each adapter's
+ * `runReadOnlyQuery` must also enforce read-only at the engine level as the authoritative guarantee
+ * (see this module's top-level comment).
+ */
+declare function assertReadOnly(sql: string): void;
+
+export { type AdapterFactory, type DatabaseAdapter, ReadOnlyViolationError, type ResolvedPageRequest, UnsupportedEngineError, assertReadOnly, resolveAdapter, resolvePageRequest };

package/dist/index.js

@@ -0,0 +1,96 @@
+// src/errors.ts
+var UnsupportedEngineError = class extends Error {
+  constructor(engine) {
+    super(`No database adapter is registered for engine "${engine}".`);
+    this.name = "UnsupportedEngineError";
+  }
+};
+var ReadOnlyViolationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ReadOnlyViolationError";
+  }
+};
+
+// src/resolve.ts
+function resolveAdapter(factories, target) {
+  const factory = factories.find((candidate) => candidate.supports(target));
+  if (!factory) {
+    throw new UnsupportedEngineError(target.engine);
+  }
+  return factory.create(target);
+}
+
+// src/pagination.ts
+var MAX_PAGE_SIZE = 200;
+function resolvePageRequest(page, pageSize) {
+  const safePage = Math.max(0, Math.floor(page));
+  const safePageSize = Math.min(Math.max(1, Math.floor(pageSize)), MAX_PAGE_SIZE);
+  return { page: safePage, pageSize: safePageSize, offset: safePage * safePageSize };
+}
+
+// src/read-only.ts
+var ALLOWED_LEADING_KEYWORDS = ["select", "with", "explain", "show", "table", "values"];
+var FORBIDDEN_KEYWORDS = [
+  "insert",
+  "update",
+  "delete",
+  "merge",
+  "truncate",
+  "drop",
+  "alter",
+  "create",
+  "grant",
+  "revoke",
+  "copy",
+  "call",
+  "do",
+  "vacuum",
+  "reindex",
+  "refresh",
+  "lock",
+  "comment",
+  "security"
+];
+function stripComments(sql) {
+  return sql.replace(/--[^\n]*/g, " ").replace(/\/\*[\s\S]*?\*\//g, " ");
+}
+function stripLiterals(sql) {
+  return sql.replace(/\$([A-Za-z_][A-Za-z0-9_]*)?\$[\s\S]*?\$\1\$/g, " ").replace(/'(?:[^']|'')*'/g, " ").replace(/"(?:[^"]|"")*"/g, " ");
+}
+function findForbiddenKeyword(sql) {
+  const lower = sql.toLowerCase();
+  return FORBIDDEN_KEYWORDS.find((keyword) => new RegExp(`\\b${keyword}\\b`).test(lower));
+}
+function assertReadOnly(sql) {
+  const withoutComments = stripComments(sql).trim();
+  if (!withoutComments) {
+    throw new ReadOnlyViolationError("Empty query.");
+  }
+  const withoutTrailingSemicolon = withoutComments.replace(/;\s*$/, "");
+  if (withoutTrailingSemicolon.includes(";")) {
+    throw new ReadOnlyViolationError(
+      "Multiple statements are not allowed in the read-only query runner."
+    );
+  }
+  const firstKeyword = withoutTrailingSemicolon.split(/\s+/)[0]?.toLowerCase() ?? "";
+  if (!ALLOWED_LEADING_KEYWORDS.includes(firstKeyword)) {
+    throw new ReadOnlyViolationError(
+      `Only read-only statements are allowed (${ALLOWED_LEADING_KEYWORDS.join(", ").toUpperCase()}). Received a statement starting with "${firstKeyword.toUpperCase()}".`
+    );
+  }
+  const forbidden = findForbiddenKeyword(stripLiterals(withoutTrailingSemicolon));
+  if (forbidden) {
+    throw new ReadOnlyViolationError(
+      `Only read-only statements are allowed. The query contains a disallowed keyword: "${forbidden.toUpperCase()}" (e.g. inside a writable CTE, which Postgres allows even though the statement starts with a read-only keyword).`
+    );
+  }
+}
+export {
+  ReadOnlyViolationError,
+  UnsupportedEngineError,
+  assertReadOnly,
+  resolveAdapter,
+  resolvePageRequest
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/resolve.ts","../src/pagination.ts","../src/read-only.ts"],"sourcesContent":["/** Thrown when no registered adapter supports a connection target. */\nexport class UnsupportedEngineError extends Error {\n  constructor(engine: string) {\n    super(`No database adapter is registered for engine \"${engine}\".`);\n    this.name = \"UnsupportedEngineError\";\n  }\n}\n\n/**\n * Thrown when a query passed to `DatabaseAdapter.runReadOnlyQuery` violates Humb's read-only\n * policy. Engine-agnostic so `packages/server` can catch it (and return 400) without depending on\n * any concrete engine package - every engine's query runner throws this same class.\n */\nexport class ReadOnlyViolationError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"ReadOnlyViolationError\";\n  }\n}\n","import type { ConnectionTarget } from \"@humbdb/core\";\nimport type { AdapterFactory, DatabaseAdapter } from \"./contract.js\";\nimport { UnsupportedEngineError } from \"./errors.js\";\n\n/** Resolve the first factory that supports the target, or throw. */\nexport function resolveAdapter(\n  factories: readonly AdapterFactory[],\n  target: ConnectionTarget\n): DatabaseAdapter {\n  const factory = factories.find((candidate) => candidate.supports(target));\n  if (!factory) {\n    throw new UnsupportedEngineError(target.engine);\n  }\n  return factory.create(target);\n}\n","/** A resolved, safely-bounded page request. */\nexport interface ResolvedPageRequest {\n  readonly page: number;\n  readonly pageSize: number;\n  readonly offset: number;\n}\n\nconst MAX_PAGE_SIZE = 200;\n\n/**\n * Clamp a requested page/pageSize into safe, non-negative bounds. Shared by every engine adapter so\n * pagination behaves identically regardless of which database is behind it - do not reimplement\n * this per engine.\n */\nexport function resolvePageRequest(page: number, pageSize: number): ResolvedPageRequest {\n  const safePage = Math.max(0, Math.floor(page));\n  const safePageSize = Math.min(Math.max(1, Math.floor(pageSize)), MAX_PAGE_SIZE);\n  return { page: safePage, pageSize: safePageSize, offset: safePage * safePageSize };\n}\n","import { ReadOnlyViolationError } from \"./errors.js\";\n\nexport { ReadOnlyViolationError } from \"./errors.js\";\n\nconst ALLOWED_LEADING_KEYWORDS = [\"select\", \"with\", \"explain\", \"show\", \"table\", \"values\"];\n\n// Data-modifying/DDL/permission keywords that must never appear anywhere in the statement, not just\n// as the leading keyword - e.g. Postgres allows *writable CTEs*\n// (`WITH x AS (DELETE FROM t RETURNING *) SELECT * FROM x`), which start with the allowed \"with\"\n// keyword but perform a real DELETE. This list is a heuristic, defense-in-depth layer, not the\n// authoritative guarantee - every engine adapter's `runReadOnlyQuery` must also enforce read-only at\n// the engine level (a Postgres `READ ONLY` transaction, a SQLite read-only connection, etc.), which\n// catches whatever this scan misses.\nconst FORBIDDEN_KEYWORDS = [\n  \"insert\",\n  \"update\",\n  \"delete\",\n  \"merge\",\n  \"truncate\",\n  \"drop\",\n  \"alter\",\n  \"create\",\n  \"grant\",\n  \"revoke\",\n  \"copy\",\n  \"call\",\n  \"do\",\n  \"vacuum\",\n  \"reindex\",\n  \"refresh\",\n  \"lock\",\n  \"comment\",\n  \"security\"\n];\n\n/** Remove SQL comments so keyword detection is not fooled by them. */\nfunction stripComments(sql: string): string {\n  return sql.replace(/--[^\\n]*/g, \" \").replace(/\\/\\*[\\s\\S]*?\\*\\//g, \" \");\n}\n\n/**\n * Remove string/identifier literals so keyword detection isn't fooled by data that happens to\n * contain a forbidden word (e.g. a string literal or a quoted column named \"update\").\n */\nfunction stripLiterals(sql: string): string {\n  return sql\n    .replace(/\\$([A-Za-z_][A-Za-z0-9_]*)?\\$[\\s\\S]*?\\$\\1\\$/g, \" \") // dollar-quoted strings (Postgres)\n    .replace(/'(?:[^']|'')*'/g, \" \") // single-quoted string literals\n    .replace(/\"(?:[^\"]|\"\")*\"/g, \" \"); // double-quoted identifiers\n}\n\nfunction findForbiddenKeyword(sql: string): string | undefined {\n  const lower = sql.toLowerCase();\n  return FORBIDDEN_KEYWORDS.find((keyword) => new RegExp(`\\\\b${keyword}\\\\b`).test(lower));\n}\n\n/**\n * Assert that a SQL string is a single read-only statement. Engine-agnostic: pure text scanning,\n * shared by every engine adapter so the heuristic behaves identically regardless of which database\n * is behind it.\n *\n * Throws {@link ReadOnlyViolationError} otherwise. This is a defense-in-depth check; each adapter's\n * `runReadOnlyQuery` must also enforce read-only at the engine level as the authoritative guarantee\n * (see this module's top-level comment).\n */\nexport function assertReadOnly(sql: string): void {\n  const withoutComments = stripComments(sql).trim();\n  if (!withoutComments) {\n    throw new ReadOnlyViolationError(\"Empty query.\");\n  }\n\n  const withoutTrailingSemicolon = withoutComments.replace(/;\\s*$/, \"\");\n  if (withoutTrailingSemicolon.includes(\";\")) {\n    throw new ReadOnlyViolationError(\n      \"Multiple statements are not allowed in the read-only query runner.\"\n    );\n  }\n\n  const firstKeyword = withoutTrailingSemicolon.split(/\\s+/)[0]?.toLowerCase() ?? \"\";\n  if (!ALLOWED_LEADING_KEYWORDS.includes(firstKeyword)) {\n    throw new ReadOnlyViolationError(\n      `Only read-only statements are allowed (${ALLOWED_LEADING_KEYWORDS.join(\", \").toUpperCase()}). ` +\n        `Received a statement starting with \"${firstKeyword.toUpperCase()}\".`\n    );\n  }\n\n  const forbidden = findForbiddenKeyword(stripLiterals(withoutTrailingSemicolon));\n  if (forbidden) {\n    throw new ReadOnlyViolationError(\n      `Only read-only statements are allowed. The query contains a disallowed keyword: ` +\n        `\"${forbidden.toUpperCase()}\" (e.g. inside a writable CTE, which Postgres allows even though ` +\n        `the statement starts with a read-only keyword).`\n    );\n  }\n}\n"],"mappings":";AACO,IAAM,yBAAN,cAAqC,MAAM;AAAA,EAChD,YAAY,QAAgB;AAC1B,UAAM,iDAAiD,MAAM,IAAI;AACjE,SAAK,OAAO;AAAA,EACd;AACF;AAOO,IAAM,yBAAN,cAAqC,MAAM;AAAA,EAChD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;;;ACbO,SAAS,eACd,WACA,QACiB;AACjB,QAAM,UAAU,UAAU,KAAK,CAAC,cAAc,UAAU,SAAS,MAAM,CAAC;AACxE,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,uBAAuB,OAAO,MAAM;AAAA,EAChD;AACA,SAAO,QAAQ,OAAO,MAAM;AAC9B;;;ACPA,IAAM,gBAAgB;AAOf,SAAS,mBAAmB,MAAc,UAAuC;AACtF,QAAM,WAAW,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,CAAC;AAC7C,QAAM,eAAe,KAAK,IAAI,KAAK,IAAI,GAAG,KAAK,MAAM,QAAQ,CAAC,GAAG,aAAa;AAC9E,SAAO,EAAE,MAAM,UAAU,UAAU,cAAc,QAAQ,WAAW,aAAa;AACnF;;;ACdA,IAAM,2BAA2B,CAAC,UAAU,QAAQ,WAAW,QAAQ,SAAS,QAAQ;AASxF,IAAM,qBAAqB;AAAA,EACzB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGA,SAAS,cAAc,KAAqB;AAC1C,SAAO,IAAI,QAAQ,aAAa,GAAG,EAAE,QAAQ,qBAAqB,GAAG;AACvE;AAMA,SAAS,cAAc,KAAqB;AAC1C,SAAO,IACJ,QAAQ,gDAAgD,GAAG,EAC3D,QAAQ,mBAAmB,GAAG,EAC9B,QAAQ,mBAAmB,GAAG;AACnC;AAEA,SAAS,qBAAqB,KAAiC;AAC7D,QAAM,QAAQ,IAAI,YAAY;AAC9B,SAAO,mBAAmB,KAAK,CAAC,YAAY,IAAI,OAAO,MAAM,OAAO,KAAK,EAAE,KAAK,KAAK,CAAC;AACxF;AAWO,SAAS,eAAe,KAAmB;AAChD,QAAM,kBAAkB,cAAc,GAAG,EAAE,KAAK;AAChD,MAAI,CAAC,iBAAiB;AACpB,UAAM,IAAI,uBAAuB,cAAc;AAAA,EACjD;AAEA,QAAM,2BAA2B,gBAAgB,QAAQ,SAAS,EAAE;AACpE,MAAI,yBAAyB,SAAS,GAAG,GAAG;AAC1C,UAAM,IAAI;AAAA,MACR;AAAA,IACF;AAAA,EACF;AAEA,QAAM,eAAe,yBAAyB,MAAM,KAAK,EAAE,CAAC,GAAG,YAAY,KAAK;AAChF,MAAI,CAAC,yBAAyB,SAAS,YAAY,GAAG;AACpD,UAAM,IAAI;AAAA,MACR,0CAA0C,yBAAyB,KAAK,IAAI,EAAE,YAAY,CAAC,0CAClD,aAAa,YAAY,CAAC;AAAA,IACrE;AAAA,EACF;AAEA,QAAM,YAAY,qBAAqB,cAAc,wBAAwB,CAAC;AAC9E,MAAI,WAAW;AACb,UAAM,IAAI;AAAA,MACR,oFACM,UAAU,YAAY,CAAC;AAAA,IAE/B;AAAA,EACF;AACF;","names":[]}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@humbdb/driver-contract",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Engine-agnostic database adapter contracts for Humb.",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@humbdb/core": "0.0.1"
+  },
+  "devDependencies": {
+    "@humbdb/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist .turbo"
+  }
+}