@humbdb/core 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,5 @@
+# @humbdb/core
+
+Shared domain types and contracts for Humb (connection targets, schema/table metadata, row pages).
+
+This package is UI-, server-, and engine-agnostic. See [`ARCHITECTURE.md`](../../ARCHITECTURE.md).

package/dist/index.d.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod';
+
+/** Database engines Humb can target. Postgres is supported first, SQLite second. */
+type DatabaseEngine = "postgres" | "sqlite";
+/** A parsed, validated database connection target. */
+interface ConnectionTarget {
+    readonly engine: DatabaseEngine;
+    /** The original connection string (may contain credentials - never log unredacted). */
+    readonly raw: string;
+}
+
+/** Metadata for a single column in a table. */
+interface ColumnMetadata {
+    readonly name: string;
+    readonly dataType: string;
+    readonly nullable: boolean;
+    readonly isPrimaryKey: boolean;
+    readonly isForeignKey: boolean;
+}
+/** Metadata for a single index on a table. */
+interface IndexMetadata {
+    readonly name: string;
+    readonly columns: string[];
+    readonly unique: boolean;
+    readonly primary: boolean;
+}
+/** Metadata for a single table. */
+interface TableMetadata {
+    readonly schema: string;
+    readonly name: string;
+    readonly columns: ColumnMetadata[];
+    readonly indexes?: IndexMetadata[];
+    readonly rowCount?: number;
+}
+
+/** A schema and the tables it contains. */
+interface SchemaMetadata {
+    readonly name: string;
+    readonly tables: string[];
+}
+/** Top-level overview of a database's structure. */
+interface DatabaseOverview {
+    readonly engine: DatabaseEngine;
+    readonly schemas: SchemaMetadata[];
+}
+
+/** A page of rows returned for a table or read-only query. */
+interface RowPage {
+    readonly columns: string[];
+    readonly rows: Array<Record<string, unknown>>;
+    readonly page: number;
+    readonly pageSize: number;
+    readonly total?: number;
+}
+
+/** Database connection status as reported by the server's health endpoint. */
+type ConnectionStatus = "connected" | "disconnected" | "unconfigured";
+/**
+ * Response shape for `GET /api/health`. Shared by the server (which produces it) and the web UI
+ * (which consumes it), so the two can never silently drift apart.
+ */
+interface HealthResponse {
+    readonly status: "ok";
+    readonly database: ConnectionStatus;
+    readonly target: string | null;
+    /** e.g. "PostgreSQL 16.1", "SQLite 3.45.0". Null when not connected or unavailable. */
+    readonly engineVersion: string | null;
+}
+
+/** A node in the Files tab's read-only file tree - either a directory or a `.sql` file. */
+interface FileNode {
+    readonly name: string;
+    readonly path: string;
+    readonly type: "file" | "directory";
+    readonly children?: FileNode[];
+}
+/** Response for `GET /api/files`. `enabled` is false when no `--files-dir` was configured. */
+interface FilesOverview {
+    readonly enabled: boolean;
+    readonly tree: FileNode[];
+}
+/** Response for `GET /api/files/content`. */
+interface FileContent {
+    readonly path: string;
+    readonly content: string;
+}
+
+type ConsoleEventLevel = "info" | "warn" | "error";
+/** A single entry in the Console tab's recent connection/query activity stream. */
+interface ConsoleEvent {
+    readonly id: number;
+    readonly timestamp: string;
+    readonly level: ConsoleEventLevel;
+    readonly message: string;
+}
+/** Response for `GET /api/console` (and the cleared state `DELETE /api/console` returns). */
+interface ConsoleEvents {
+    readonly events: ConsoleEvent[];
+}
+
+/** Thrown when a connection target cannot be parsed or is unsupported. */
+declare class InvalidConnectionTargetError extends Error {
+    constructor(message: string);
+}
+
+/** Default local port Humb's server listens on. */
+declare const DEFAULT_PORT = 7717;
+/**
+ * Redact credentials from a connection string so it is safe to log.
+ * Returns a best-effort redacted form; on parse failure returns a generic mask.
+ */
+declare function redactConnectionString(raw: string): string;
+/**
+ * Parse and validate a user-provided database target at the boundary.
+ * Throws {@link InvalidConnectionTargetError} with actionable guidance on failure.
+ */
+declare function parseConnectionTarget(input: string | undefined): ConnectionTarget;
+
+/**
+ * Request body schema for `POST /api/query`. Shared so the server enforces the same shape the web
+ * UI's query form (and any future client) can validate against before sending a request.
+ */
+declare const runQuerySchema: z.ZodObject<{
+    sql: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    sql: string;
+}, {
+    sql: string;
+}>;
+type RunQueryRequest = z.infer<typeof runQuerySchema>;
+
+/** Query-string schema for `GET /api/tables/:schema/:table/rows` pagination. */
+declare const rowsQuerySchema: z.ZodObject<{
+    page: z.ZodDefault<z.ZodNumber>;
+    pageSize: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    page: number;
+    pageSize: number;
+}, {
+    page?: number | undefined;
+    pageSize?: number | undefined;
+}>;
+type RowsQuery = z.infer<typeof rowsQuerySchema>;
+
+/** Query-string schema for `GET /api/files/content`. */
+declare const fileContentQuerySchema: z.ZodObject<{
+    path: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+}, {
+    path: string;
+}>;
+type FileContentQuery = z.infer<typeof fileContentQuerySchema>;
+
+export { type ColumnMetadata, type ConnectionStatus, type ConnectionTarget, type ConsoleEvent, type ConsoleEventLevel, type ConsoleEvents, DEFAULT_PORT, type DatabaseEngine, type DatabaseOverview, type FileContent, type FileContentQuery, type FileNode, type FilesOverview, type HealthResponse, type IndexMetadata, InvalidConnectionTargetError, type RowPage, type RowsQuery, type RunQueryRequest, type SchemaMetadata, type TableMetadata, fileContentQuerySchema, parseConnectionTarget, redactConnectionString, rowsQuerySchema, runQuerySchema };

package/dist/index.js

@@ -0,0 +1,87 @@
+// src/errors.ts
+var InvalidConnectionTargetError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidConnectionTargetError";
+  }
+};
+
+// src/connection-target.ts
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { fileURLToPath } from "url";
+var POSTGRES_PROTOCOLS = /* @__PURE__ */ new Set(["postgres:", "postgresql:"]);
+var DEFAULT_PORT = 7717;
+function redactConnectionString(raw) {
+  try {
+    const url = new URL(raw);
+    if (url.password) {
+      url.password = "***";
+    }
+    return url.toString();
+  } catch {
+    return "<unparseable connection string>";
+  }
+}
+function resolveSqliteTarget(raw, path) {
+  const resolvedPath = resolve(path);
+  if (!existsSync(resolvedPath)) {
+    throw new InvalidConnectionTargetError(
+      `No file found at "${resolvedPath}". Expected a path to an existing SQLite file (e.g. ./app.db), or a Postgres connection string (postgres://user:pass@localhost:5432/mydb).`
+    );
+  }
+  return { engine: "sqlite", raw };
+}
+function parseConnectionTarget(input) {
+  const trimmed = input?.trim();
+  if (!trimmed) {
+    throw new InvalidConnectionTargetError(
+      "No database target provided. Expected a Postgres connection string (e.g. postgres://user:pass@localhost:5432/mydb) or a path to a SQLite file (e.g. ./app.db)."
+    );
+  }
+  let url;
+  try {
+    url = new URL(trimmed);
+  } catch {
+    url = void 0;
+  }
+  if (url) {
+    if (POSTGRES_PROTOCOLS.has(url.protocol)) {
+      return { engine: "postgres", raw: trimmed };
+    }
+    if (url.protocol === "file:") {
+      return resolveSqliteTarget(trimmed, fileURLToPath(url));
+    }
+    throw new InvalidConnectionTargetError(
+      `Unsupported database target protocol "${url.protocol}". Humb currently supports Postgres (postgres:// or postgresql://) and SQLite (a file path).`
+    );
+  }
+  return resolveSqliteTarget(trimmed, trimmed);
+}
+
+// src/validation/query.ts
+import { z } from "zod";
+var runQuerySchema = z.object({ sql: z.string().min(1) });
+
+// src/validation/rows.ts
+import { z as z2 } from "zod";
+var rowsQuerySchema = z2.object({
+  page: z2.coerce.number().int().min(0).default(0),
+  pageSize: z2.coerce.number().int().min(1).max(200).default(50)
+});
+
+// src/validation/files.ts
+import { z as z3 } from "zod";
+var fileContentQuerySchema = z3.object({
+  path: z3.string().min(1)
+});
+export {
+  DEFAULT_PORT,
+  InvalidConnectionTargetError,
+  fileContentQuerySchema,
+  parseConnectionTarget,
+  redactConnectionString,
+  rowsQuerySchema,
+  runQuerySchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/connection-target.ts","../src/validation/query.ts","../src/validation/rows.ts","../src/validation/files.ts"],"sourcesContent":["/** Thrown when a connection target cannot be parsed or is unsupported. */\nexport class InvalidConnectionTargetError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"InvalidConnectionTargetError\";\n  }\n}\n","import { existsSync } from \"node:fs\";\nimport { resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { InvalidConnectionTargetError } from \"./errors.js\";\nimport type { ConnectionTarget } from \"./types/connection.js\";\n\nconst POSTGRES_PROTOCOLS = new Set([\"postgres:\", \"postgresql:\"]);\n\n/** Default local port Humb's server listens on. */\nexport const DEFAULT_PORT = 7717;\n\n/**\n * Redact credentials from a connection string so it is safe to log.\n * Returns a best-effort redacted form; on parse failure returns a generic mask.\n */\nexport function redactConnectionString(raw: string): string {\n  try {\n    const url = new URL(raw);\n    if (url.password) {\n      url.password = \"***\";\n    }\n    return url.toString();\n  } catch {\n    return \"<unparseable connection string>\";\n  }\n}\n\n/**\n * Resolve a candidate SQLite file path (bare path or `file:` URL) into a {@link ConnectionTarget}.\n * Existence is checked here, at the parse boundary, so the CLI fails fast with the exact resolved\n * path it looked for, matching Postgres's fail-fast-on-invalid-input behavior - see\n * `docs/product-specs/connect-and-inspect-sqlite.md`.\n */\nfunction resolveSqliteTarget(raw: string, path: string): ConnectionTarget {\n  const resolvedPath = resolve(path);\n  if (!existsSync(resolvedPath)) {\n    throw new InvalidConnectionTargetError(\n      `No file found at \"${resolvedPath}\". Expected a path to an existing SQLite file (e.g. ` +\n        \"./app.db), or a Postgres connection string (postgres://user:pass@localhost:5432/mydb).\"\n    );\n  }\n  return { engine: \"sqlite\", raw };\n}\n\n/**\n * Parse and validate a user-provided database target at the boundary.\n * Throws {@link InvalidConnectionTargetError} with actionable guidance on failure.\n */\nexport function parseConnectionTarget(input: string | undefined): ConnectionTarget {\n  const trimmed = input?.trim();\n  if (!trimmed) {\n    throw new InvalidConnectionTargetError(\n      \"No database target provided. Expected a Postgres connection string (e.g. \" +\n        \"postgres://user:pass@localhost:5432/mydb) or a path to a SQLite file (e.g. ./app.db).\"\n    );\n  }\n\n  let url: URL | undefined;\n  try {\n    url = new URL(trimmed);\n  } catch {\n    url = undefined;\n  }\n\n  if (url) {\n    if (POSTGRES_PROTOCOLS.has(url.protocol)) {\n      return { engine: \"postgres\", raw: trimmed };\n    }\n    if (url.protocol === \"file:\") {\n      return resolveSqliteTarget(trimmed, fileURLToPath(url));\n    }\n    throw new InvalidConnectionTargetError(\n      `Unsupported database target protocol \"${url.protocol}\". ` +\n        \"Humb currently supports Postgres (postgres:// or postgresql://) and SQLite (a file path).\"\n    );\n  }\n\n  // Not URL-shaped at all (e.g. `./app.db`, `data.sqlite`) - treat as a candidate SQLite file path.\n  return resolveSqliteTarget(trimmed, trimmed);\n}\n","import { z } from \"zod\";\n\n/**\n * Request body schema for `POST /api/query`. Shared so the server enforces the same shape the web\n * UI's query form (and any future client) can validate against before sending a request.\n */\nexport const runQuerySchema = z.object({ sql: z.string().min(1) });\nexport type RunQueryRequest = z.infer<typeof runQuerySchema>;\n","import { z } from \"zod\";\n\n/** Query-string schema for `GET /api/tables/:schema/:table/rows` pagination. */\nexport const rowsQuerySchema = z.object({\n  page: z.coerce.number().int().min(0).default(0),\n  pageSize: z.coerce.number().int().min(1).max(200).default(50)\n});\nexport type RowsQuery = z.infer<typeof rowsQuerySchema>;\n","import { z } from \"zod\";\n\n/** Query-string schema for `GET /api/files/content`. */\nexport const fileContentQuerySchema = z.object({\n  path: z.string().min(1)\n});\nexport type FileContentQuery = z.infer<typeof fileContentQuerySchema>;\n"],"mappings":";AACO,IAAM,+BAAN,cAA2C,MAAM;AAAA,EACtD,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;;;ACNA,SAAS,kBAAkB;AAC3B,SAAS,eAAe;AACxB,SAAS,qBAAqB;AAI9B,IAAM,qBAAqB,oBAAI,IAAI,CAAC,aAAa,aAAa,CAAC;AAGxD,IAAM,eAAe;AAMrB,SAAS,uBAAuB,KAAqB;AAC1D,MAAI;AACF,UAAM,MAAM,IAAI,IAAI,GAAG;AACvB,QAAI,IAAI,UAAU;AAChB,UAAI,WAAW;AAAA,IACjB;AACA,WAAO,IAAI,SAAS;AAAA,EACtB,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAQA,SAAS,oBAAoB,KAAa,MAAgC;AACxE,QAAM,eAAe,QAAQ,IAAI;AACjC,MAAI,CAAC,WAAW,YAAY,GAAG;AAC7B,UAAM,IAAI;AAAA,MACR,qBAAqB,YAAY;AAAA,IAEnC;AAAA,EACF;AACA,SAAO,EAAE,QAAQ,UAAU,IAAI;AACjC;AAMO,SAAS,sBAAsB,OAA6C;AACjF,QAAM,UAAU,OAAO,KAAK;AAC5B,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI;AAAA,MACR;AAAA,IAEF;AAAA,EACF;AAEA,MAAI;AACJ,MAAI;AACF,UAAM,IAAI,IAAI,OAAO;AAAA,EACvB,QAAQ;AACN,UAAM;AAAA,EACR;AAEA,MAAI,KAAK;AACP,QAAI,mBAAmB,IAAI,IAAI,QAAQ,GAAG;AACxC,aAAO,EAAE,QAAQ,YAAY,KAAK,QAAQ;AAAA,IAC5C;AACA,QAAI,IAAI,aAAa,SAAS;AAC5B,aAAO,oBAAoB,SAAS,cAAc,GAAG,CAAC;AAAA,IACxD;AACA,UAAM,IAAI;AAAA,MACR,yCAAyC,IAAI,QAAQ;AAAA,IAEvD;AAAA,EACF;AAGA,SAAO,oBAAoB,SAAS,OAAO;AAC7C;;;AC/EA,SAAS,SAAS;AAMX,IAAM,iBAAiB,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,CAAC;;;ACNjE,SAAS,KAAAA,UAAS;AAGX,IAAM,kBAAkBA,GAAE,OAAO;AAAA,EACtC,MAAMA,GAAE,OAAO,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,QAAQ,CAAC;AAAA,EAC9C,UAAUA,GAAE,OAAO,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE,IAAI,GAAG,EAAE,QAAQ,EAAE;AAC9D,CAAC;;;ACND,SAAS,KAAAC,UAAS;AAGX,IAAM,yBAAyBA,GAAE,OAAO;AAAA,EAC7C,MAAMA,GAAE,OAAO,EAAE,IAAI,CAAC;AACxB,CAAC;","names":["z","z"]}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@humbdb/core",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Shared domain types and 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": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@humbdb/config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "clean": "rimraf dist .turbo"
+  }
+}