@geekmidas/db 10.0.0-alpha.14 → 10.0.0-alpha.140

package/README.md

@@ -9,6 +9,7 @@ Database utilities for Kysely with flexible transaction management. Provides hel
 - ✅ **Type-Safe**: Full TypeScript support with generic database schemas
 - ✅ **Connection Abstraction**: Single helper for all database connection types
 - ✅ **Zero Dependencies**: Only peer dependency on Kysely
+- ✅ **Introspection** (`@geekmidas/db/introspect`): schemas, tables and rows as functions and a read-only JSON API
 
 ## Installation
 
@@ -70,6 +71,22 @@ async function createUserWithPost(
 }
 ```
 
+## Introspection
+
+`@geekmidas/db/introspect` reads a Postgres database's structure and pages
+through its rows, read-only — as functions, and as a fetch-style JSON handler
+with no HTTP framework behind it. `gkm dev` serves it at `/__gkm/db`.
+
+```typescript
+import { createIntrospectionHandler } from '@geekmidas/db/introspect';
+
+const handler = createIntrospectionHandler({ db, basePath: '/__db' });
+app.all('/__db/*', (c) => handler(c.req.raw));
+// GET /__db/schemas, /__db/tables, /__db/tables/users/rows?pageSize=20
+```
+
+It returns every row to whoever can reach it, so mount it only in development.
+
 ## API Reference
 
 ### `withTransaction`

package/dist/errors.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;wBAyBgB,kBAAkB;;;;;;;8BAiBZ,6BAA6B;EACtC,YAAA;;;qBAOA,4BAA4B;EAAA;;;;;;;;;qBAa5B,4BAA4B;EAAA"}
+{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;wBAyBgB,kBAAkB;;;;;;;8BAiBZ,6BAA6B;EAClD,YAAY;;;qBAOA,4BAA4B;EACxC;;;;;;;;;qBAYY,4BAA4B;EACxC"}

package/dist/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;wBAyBgB,kBAAkB;;;;;;;8BAiBZ,6BAA6B;EACtC,YAAA;;;qBAOA,4BAA4B;EAAA;;;;;;;;;qBAa5B,4BAA4B;EAAA"}
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;wBAyBgB,kBAAkB;;;;;;;8BAiBZ,6BAA6B;EAClD,YAAY;;;qBAOA,4BAA4B;EACxC;;;;;;;;;qBAYY,4BAA4B;EACxC"}

package/dist/introspect/DataBrowser.cjs

@@ -0,0 +1,117 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_pagination = require("../pagination.cjs");
+const require_introspect_errors = require("./errors.cjs");
+const require_introspect_filtering = require("./filtering.cjs");
+const require_introspect_introspection = require("./introspection.cjs");
+//#region src/introspect/DataBrowser.ts
+/** How long an introspected schema is reused before it is read again. */
+const SCHEMA_TTL_MS = 6e4;
+const MAX_PAGE_SIZE = 100;
+/**
+* Reads a Postgres database's structure and pages through its rows, read-only.
+*
+* @example
+* ```typescript
+* const browser = new DataBrowser({ db });
+*
+* const { tables } = await browser.getSchema();
+* const page = await browser.query({ table: 'users', pageSize: 20 });
+* const next = await browser.query({ table: 'users', cursor: page.nextCursor });
+* ```
+*/
+var DataBrowser = class {
+	db;
+	schemas;
+	cursor;
+	tableCursors;
+	excludeTables;
+	defaultPageSize;
+	schemaCache;
+	constructor(options) {
+		this.db = options.db;
+		this.schemas = options.schemas ?? ["public"];
+		this.cursor = options.cursor;
+		this.tableCursors = options.tableCursors ?? {};
+		this.excludeTables = options.excludeTables ?? [];
+		this.defaultPageSize = options.defaultPageSize ?? 50;
+	}
+	/** Every schema the database has, browsable or not. */
+	listSchemas() {
+		return require_introspect_introspection.listSchemas(this.db);
+	}
+	/**
+	* The browsable tables. Cached for a minute, since a migration is rare and
+	* introspection is several catalog queries per table.
+	*/
+	async getSchema(forceRefresh = false) {
+		const now = Date.now();
+		if (!forceRefresh && this.schemaCache && now < this.schemaCache.expires) return this.schemaCache.info;
+		const info = await require_introspect_introspection.introspectSchema(this.db, {
+			schemas: this.schemas,
+			excludeTables: this.excludeTables
+		});
+		this.schemaCache = {
+			info,
+			expires: now + SCHEMA_TTL_MS
+		};
+		return info;
+	}
+	/** One table, or null when it is not browsable. */
+	async getTableInfo(tableName, schema = this.schemas[0] ?? "public") {
+		const { tables } = await this.getSchema();
+		return tables.find((t) => t.name === tableName && t.schema === schema) ?? null;
+	}
+	/**
+	* A page of a table's rows, filtered and sorted.
+	*
+	* @throws {TableNotFound} the table is not browsable
+	* @throws {ColumnNotFound} a filter or sort names a column it does not have
+	* @throws {UnsupportedFilterOperator} a filter's operator does not apply
+	* @throws {InvalidCursor} the cursor did not come from a previous page
+	*/
+	async query(options) {
+		const schema = options.schema ?? this.schemas[0] ?? "public";
+		const table = await this.getTableInfo(options.table, schema);
+		if (!table) throw new require_introspect_errors.TableNotFound(options.table, schema);
+		const cursor = this.getCursorConfig(table);
+		const pageSize = Math.min(options.pageSize ?? this.defaultPageSize, MAX_PAGE_SIZE);
+		let query = this.db.withSchema(schema).selectFrom(table.name).selectAll();
+		if (options.filters?.length) query = require_introspect_filtering.applyFilters(query, options.filters, table);
+		if (options.sort?.length) query = require_introspect_filtering.applySorting(query, options.sort, table);
+		else if (cursor) query = query.orderBy(cursor.field, cursor.direction);
+		if (options.cursor && cursor) {
+			const after = require_pagination.decodeCursor(options.cursor);
+			const operator = cursor.direction === "asc" ? ">" : "<";
+			query = query.where(cursor.field, operator, after);
+		}
+		const rows = await query.limit(pageSize + 1).execute();
+		const hasMore = rows.length > pageSize;
+		const page = hasMore ? rows.slice(0, pageSize) : rows;
+		const last = page[page.length - 1];
+		const first = page[0];
+		return {
+			rows: page,
+			hasMore,
+			nextCursor: hasMore && cursor && last ? require_pagination.encodeCursor(last[cursor.field]) : null,
+			prevCursor: options.cursor && cursor && first ? require_pagination.encodeCursor(first[cursor.field]) : null
+		};
+	}
+	/**
+	* The cursor a table pages by: its own, the default, or its primary key
+	* when that is one column. Undefined means the table has nothing unique to
+	* page by, so it is read a page at a time with no next cursor.
+	*/
+	getCursorConfig(table) {
+		const configured = this.tableCursors[table.name] ?? this.cursor;
+		if (configured) return configured;
+		const [key, ...rest] = table.primaryKey;
+		if (key && rest.length === 0) return {
+			field: key,
+			direction: "asc"
+		};
+	}
+};
+//#endregion
+exports.DataBrowser = DataBrowser;
+
+//# sourceMappingURL=DataBrowser.cjs.map

package/dist/introspect/DataBrowser.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataBrowser.cjs","names":["listSchemas","introspectSchema","TableNotFound","applyFilters","applySorting","decodeCursor","encodeCursor"],"sources":["../../src/introspect/DataBrowser.ts"],"sourcesContent":["import type { Kysely, SelectQueryBuilder } from 'kysely';\nimport { Direction, decodeCursor, encodeCursor } from '../pagination';\nimport { TableNotFound } from './errors';\nimport { applyFilters, applySorting } from './filtering';\nimport { introspectSchema, listSchemas } from './introspection';\nimport type {\n\tCursorConfig,\n\tDataBrowserOptions,\n\tQueryOptions,\n\tQueryResult,\n\tSchemaInfo,\n\tTableInfo,\n} from './types';\n\n/** How long an introspected schema is reused before it is read again. */\nconst SCHEMA_TTL_MS = 60 * 1000;\nconst MAX_PAGE_SIZE = 100;\n\n/**\n * Reads a Postgres database's structure and pages through its rows, read-only.\n *\n * @example\n * ```typescript\n * const browser = new DataBrowser({ db });\n *\n * const { tables } = await browser.getSchema();\n * const page = await browser.query({ table: 'users', pageSize: 20 });\n * const next = await browser.query({ table: 'users', cursor: page.nextCursor });\n * ```\n */\nexport class DataBrowser<DB = unknown> {\n\treadonly db: Kysely<DB>;\n\treadonly schemas: string[];\n\tprivate readonly cursor?: CursorConfig;\n\tprivate readonly tableCursors: Record<string, CursorConfig>;\n\tprivate readonly excludeTables: string[];\n\tprivate readonly defaultPageSize: number;\n\tprivate schemaCache?: { info: SchemaInfo; expires: number };\n\n\tconstructor(options: DataBrowserOptions<DB>) {\n\t\tthis.db = options.db;\n\t\tthis.schemas = options.schemas ?? ['public'];\n\t\tthis.cursor = options.cursor;\n\t\tthis.tableCursors = options.tableCursors ?? {};\n\t\tthis.excludeTables = options.excludeTables ?? [];\n\t\tthis.defaultPageSize = options.defaultPageSize ?? 50;\n\t}\n\n\t/** Every schema the database has, browsable or not. */\n\tlistSchemas(): Promise<string[]> {\n\t\treturn listSchemas(this.db);\n\t}\n\n\t/**\n\t * The browsable tables. Cached for a minute, since a migration is rare and\n\t * introspection is several catalog queries per table.\n\t */\n\tasync getSchema(forceRefresh = false): Promise<SchemaInfo> {\n\t\tconst now = Date.now();\n\t\tif (!forceRefresh && this.schemaCache && now < this.schemaCache.expires) {\n\t\t\treturn this.schemaCache.info;\n\t\t}\n\n\t\tconst info = await introspectSchema(this.db, {\n\t\t\tschemas: this.schemas,\n\t\t\texcludeTables: this.excludeTables,\n\t\t});\n\t\tthis.schemaCache = { info, expires: now + SCHEMA_TTL_MS };\n\t\treturn info;\n\t}\n\n\t/** One table, or null when it is not browsable. */\n\tasync getTableInfo(\n\t\ttableName: string,\n\t\tschema = this.schemas[0] ?? 'public',\n\t): Promise<TableInfo | null> {\n\t\tconst { tables } = await this.getSchema();\n\t\treturn (\n\t\t\ttables.find((t) => t.name === tableName && t.schema === schema) ?? null\n\t\t);\n\t}\n\n\t/**\n\t * A page of a table's rows, filtered and sorted.\n\t *\n\t * @throws {TableNotFound} the table is not browsable\n\t * @throws {ColumnNotFound} a filter or sort names a column it does not have\n\t * @throws {UnsupportedFilterOperator} a filter's operator does not apply\n\t * @throws {InvalidCursor} the cursor did not come from a previous page\n\t */\n\tasync query(options: QueryOptions): Promise<QueryResult> {\n\t\tconst schema = options.schema ?? this.schemas[0] ?? 'public';\n\t\tconst table = await this.getTableInfo(options.table, schema);\n\t\tif (!table) {\n\t\t\tthrow new TableNotFound(options.table, schema);\n\t\t}\n\n\t\tconst cursor = this.getCursorConfig(table);\n\t\tconst pageSize = Math.min(\n\t\t\toptions.pageSize ?? this.defaultPageSize,\n\t\t\tMAX_PAGE_SIZE,\n\t\t);\n\n\t\t// The table was found by introspection; the query's static types only\n\t\t// know the tables the application declared.\n\t\tlet query = (this.db as Kysely<any>)\n\t\t\t.withSchema(schema)\n\t\t\t.selectFrom(table.name)\n\t\t\t.selectAll() as SelectQueryBuilder<any, any, Record<string, unknown>>;\n\n\t\tif (options.filters?.length) {\n\t\t\tquery = applyFilters(query, options.filters, table);\n\t\t}\n\n\t\tif (options.sort?.length) {\n\t\t\tquery = applySorting(query, options.sort, table);\n\t\t} else if (cursor) {\n\t\t\tquery = query.orderBy(cursor.field, cursor.direction);\n\t\t}\n\n\t\tif (options.cursor && cursor) {\n\t\t\tconst after = decodeCursor(options.cursor);\n\t\t\tconst operator = cursor.direction === Direction.Asc ? '>' : '<';\n\t\t\tquery = query.where(cursor.field, operator, after);\n\t\t}\n\n\t\t// One more row than the page, so whether there is a next page is known\n\t\t// without counting.\n\t\tconst rows = await query.limit(pageSize + 1).execute();\n\t\tconst hasMore = rows.length > pageSize;\n\t\tconst page = hasMore ? rows.slice(0, pageSize) : rows;\n\n\t\tconst last = page[page.length - 1];\n\t\tconst first = page[0];\n\n\t\treturn {\n\t\t\trows: page,\n\t\t\thasMore,\n\t\t\tnextCursor:\n\t\t\t\thasMore && cursor && last ? encodeCursor(last[cursor.field]) : null,\n\t\t\t// Only known to exist when this page was reached through a cursor.\n\t\t\tprevCursor:\n\t\t\t\toptions.cursor && cursor && first\n\t\t\t\t\t? encodeCursor(first[cursor.field])\n\t\t\t\t\t: null,\n\t\t};\n\t}\n\n\t/**\n\t * The cursor a table pages by: its own, the default, or its primary key\n\t * when that is one column. Undefined means the table has nothing unique to\n\t * page by, so it is read a page at a time with no next cursor.\n\t */\n\tgetCursorConfig(table: TableInfo): CursorConfig | undefined {\n\t\tconst configured = this.tableCursors[table.name] ?? this.cursor;\n\t\tif (configured) return configured;\n\n\t\tconst [key, ...rest] = table.primaryKey;\n\t\tif (key && rest.length === 0) {\n\t\t\treturn { field: key, direction: Direction.Asc };\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"],"mappings":";;;;;;;AAeA,MAAM,gBAAgB;AACtB,MAAM,gBAAgB;;;;;;;;;;;;;AActB,IAAa,cAAb,MAAuC;CACtC;CACA;CACA;CACA;CACA;CACA;CACA;CAEA,YAAY,SAAiC;EAC5C,KAAK,KAAK,QAAQ;EAClB,KAAK,UAAU,QAAQ,WAAW,CAAC,QAAQ;EAC3C,KAAK,SAAS,QAAQ;EACtB,KAAK,eAAe,QAAQ,gBAAgB,CAAC;EAC7C,KAAK,gBAAgB,QAAQ,iBAAiB,CAAC;EAC/C,KAAK,kBAAkB,QAAQ,mBAAmB;CACnD;;CAGA,cAAiC;EAChC,OAAOA,iCAAAA,YAAY,KAAK,EAAE;CAC3B;;;;;CAMA,MAAM,UAAU,eAAe,OAA4B;EAC1D,MAAM,MAAM,KAAK,IAAI;EACrB,IAAI,CAAC,gBAAgB,KAAK,eAAe,MAAM,KAAK,YAAY,SAC/D,OAAO,KAAK,YAAY;EAGzB,MAAM,OAAO,MAAMC,iCAAAA,iBAAiB,KAAK,IAAI;GAC5C,SAAS,KAAK;GACd,eAAe,KAAK;EACrB,CAAC;EACD,KAAK,cAAc;GAAE;GAAM,SAAS,MAAM;EAAc;EACxD,OAAO;CACR;;CAGA,MAAM,aACL,WACA,SAAS,KAAK,QAAQ,MAAM,UACA;EAC5B,MAAM,EAAE,WAAW,MAAM,KAAK,UAAU;EACxC,OACC,OAAO,MAAM,MAAM,EAAE,SAAS,aAAa,EAAE,WAAW,MAAM,KAAK;CAErE;;;;;;;;;CAUA,MAAM,MAAM,SAA6C;EACxD,MAAM,SAAS,QAAQ,UAAU,KAAK,QAAQ,MAAM;EACpD,MAAM,QAAQ,MAAM,KAAK,aAAa,QAAQ,OAAO,MAAM;EAC3D,IAAI,CAAC,OACJ,MAAM,IAAIC,0BAAAA,cAAc,QAAQ,OAAO,MAAM;EAG9C,MAAM,SAAS,KAAK,gBAAgB,KAAK;EACzC,MAAM,WAAW,KAAK,IACrB,QAAQ,YAAY,KAAK,iBACzB,aACD;EAIA,IAAI,QAAS,KAAK,GAChB,WAAW,MAAM,CAAC,CAClB,WAAW,MAAM,IAAI,CAAC,CACtB,UAAU;EAEZ,IAAI,QAAQ,SAAS,QACpB,QAAQC,6BAAAA,aAAa,OAAO,QAAQ,SAAS,KAAK;EAGnD,IAAI,QAAQ,MAAM,QACjB,QAAQC,6BAAAA,aAAa,OAAO,QAAQ,MAAM,KAAK;OACzC,IAAI,QACV,QAAQ,MAAM,QAAQ,OAAO,OAAO,OAAO,SAAS;EAGrD,IAAI,QAAQ,UAAU,QAAQ;GAC7B,MAAM,QAAQC,mBAAAA,aAAa,QAAQ,MAAM;GACzC,MAAM,WAAW,OAAO,cAAA,QAA8B,MAAM;GAC5D,QAAQ,MAAM,MAAM,OAAO,OAAO,UAAU,KAAK;EAClD;EAIA,MAAM,OAAO,MAAM,MAAM,MAAM,WAAW,CAAC,CAAC,CAAC,QAAQ;EACrD,MAAM,UAAU,KAAK,SAAS;EAC9B,MAAM,OAAO,UAAU,KAAK,MAAM,GAAG,QAAQ,IAAI;EAEjD,MAAM,OAAO,KAAK,KAAK,SAAS;EAChC,MAAM,QAAQ,KAAK;EAEnB,OAAO;GACN,MAAM;GACN;GACA,YACC,WAAW,UAAU,OAAOC,mBAAAA,aAAa,KAAK,OAAO,MAAM,IAAI;GAEhE,YACC,QAAQ,UAAU,UAAU,QACzBA,mBAAAA,aAAa,MAAM,OAAO,MAAM,IAChC;EACL;CACD;;;;;;CAOA,gBAAgB,OAA4C;EAC3D,MAAM,aAAa,KAAK,aAAa,MAAM,SAAS,KAAK;EACzD,IAAI,YAAY,OAAO;EAEvB,MAAM,CAAC,KAAK,GAAG,QAAQ,MAAM;EAC7B,IAAI,OAAO,KAAK,WAAW,GAC1B,OAAO;GAAE,OAAO;GAAK,WAAA;EAAyB;CAIhD;AACD"}

package/dist/introspect/DataBrowser.d.cts

@@ -0,0 +1,51 @@
+import { CursorConfig, DataBrowserOptions, QueryOptions, QueryResult, SchemaInfo, TableInfo } from "./types.cjs";
+import { Kysely } from "kysely";
+//#region src/introspect/DataBrowser.d.ts
+/**
+ * Reads a Postgres database's structure and pages through its rows, read-only.
+ *
+ * @example
+ * ```typescript
+ * const browser = new DataBrowser({ db });
+ *
+ * const { tables } = await browser.getSchema();
+ * const page = await browser.query({ table: 'users', pageSize: 20 });
+ * const next = await browser.query({ table: 'users', cursor: page.nextCursor });
+ * ```
+ */
+export declare class DataBrowser<DB = unknown> {
+  readonly db: Kysely<DB>;
+  readonly schemas: string[];
+  private readonly cursor?;
+  private readonly tableCursors;
+  private readonly excludeTables;
+  private readonly defaultPageSize;
+  private schemaCache?;
+  constructor(options: DataBrowserOptions<DB>);
+  /** Every schema the database has, browsable or not. */
+  listSchemas(): Promise<string[]>;
+  /**
+   * The browsable tables. Cached for a minute, since a migration is rare and
+   * introspection is several catalog queries per table.
+   */
+  getSchema(forceRefresh?: boolean): Promise<SchemaInfo>;
+  /** One table, or null when it is not browsable. */
+  getTableInfo(tableName: string, schema?: string): Promise<TableInfo | null>;
+  /**
+   * A page of a table's rows, filtered and sorted.
+   *
+   * @throws {TableNotFound} the table is not browsable
+   * @throws {ColumnNotFound} a filter or sort names a column it does not have
+   * @throws {UnsupportedFilterOperator} a filter's operator does not apply
+   * @throws {InvalidCursor} the cursor did not come from a previous page
+   */
+  query(options: QueryOptions): Promise<QueryResult>;
+  /**
+   * The cursor a table pages by: its own, the default, or its primary key
+   * when that is one column. Undefined means the table has nothing unique to
+   * page by, so it is read a page at a time with no next cursor.
+   */
+  getCursorConfig(table: TableInfo): CursorConfig | undefined;
+}
+//#endregion
+//# sourceMappingURL=DataBrowser.d.cts.map

package/dist/introspect/DataBrowser.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataBrowser.d.cts","names":[],"sources":["../../src/introspect/DataBrowser.ts"],"mappings":";;;;;;;;;;;;;;;qBA8Ba,YAAY;WACf,IAAI,OAAO;WACX;mBACQ;mBACA;mBACA;mBACA;UACT;EAER,YAAY,SAAS,mBAAmB;;EAUxC,eAAe;;;;;EAQT,UAAU,yBAAuB,QAAQ;;EAezC,aACL,mBACA,kBACE,QAAQ;;;;;;;;;EAeL,MAAM,SAAS,eAAe,QAAQ;;;;;;EA+D5C,gBAAgB,OAAO,YAAY"}

package/dist/introspect/DataBrowser.d.mts

@@ -0,0 +1,51 @@
+import { CursorConfig, DataBrowserOptions, QueryOptions, QueryResult, SchemaInfo, TableInfo } from "./types.mjs";
+import { Kysely } from "kysely";
+//#region src/introspect/DataBrowser.d.ts
+/**
+ * Reads a Postgres database's structure and pages through its rows, read-only.
+ *
+ * @example
+ * ```typescript
+ * const browser = new DataBrowser({ db });
+ *
+ * const { tables } = await browser.getSchema();
+ * const page = await browser.query({ table: 'users', pageSize: 20 });
+ * const next = await browser.query({ table: 'users', cursor: page.nextCursor });
+ * ```
+ */
+export declare class DataBrowser<DB = unknown> {
+  readonly db: Kysely<DB>;
+  readonly schemas: string[];
+  private readonly cursor?;
+  private readonly tableCursors;
+  private readonly excludeTables;
+  private readonly defaultPageSize;
+  private schemaCache?;
+  constructor(options: DataBrowserOptions<DB>);
+  /** Every schema the database has, browsable or not. */
+  listSchemas(): Promise<string[]>;
+  /**
+   * The browsable tables. Cached for a minute, since a migration is rare and
+   * introspection is several catalog queries per table.
+   */
+  getSchema(forceRefresh?: boolean): Promise<SchemaInfo>;
+  /** One table, or null when it is not browsable. */
+  getTableInfo(tableName: string, schema?: string): Promise<TableInfo | null>;
+  /**
+   * A page of a table's rows, filtered and sorted.
+   *
+   * @throws {TableNotFound} the table is not browsable
+   * @throws {ColumnNotFound} a filter or sort names a column it does not have
+   * @throws {UnsupportedFilterOperator} a filter's operator does not apply
+   * @throws {InvalidCursor} the cursor did not come from a previous page
+   */
+  query(options: QueryOptions): Promise<QueryResult>;
+  /**
+   * The cursor a table pages by: its own, the default, or its primary key
+   * when that is one column. Undefined means the table has nothing unique to
+   * page by, so it is read a page at a time with no next cursor.
+   */
+  getCursorConfig(table: TableInfo): CursorConfig | undefined;
+}
+//#endregion
+//# sourceMappingURL=DataBrowser.d.mts.map

package/dist/introspect/DataBrowser.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataBrowser.d.mts","names":[],"sources":["../../src/introspect/DataBrowser.ts"],"mappings":";;;;;;;;;;;;;;;qBA8Ba,YAAY;WACf,IAAI,OAAO;WACX;mBACQ;mBACA;mBACA;mBACA;UACT;EAER,YAAY,SAAS,mBAAmB;;EAUxC,eAAe;;;;;EAQT,UAAU,yBAAuB,QAAQ;;EAezC,aACL,mBACA,kBACE,QAAQ;;;;;;;;;EAeL,MAAM,SAAS,eAAe,QAAQ;;;;;;EA+D5C,gBAAgB,OAAO,YAAY"}

package/dist/introspect/DataBrowser.mjs

@@ -0,0 +1,116 @@
+import { decodeCursor, encodeCursor } from "../pagination.mjs";
+import { TableNotFound } from "./errors.mjs";
+import { applyFilters, applySorting } from "./filtering.mjs";
+import { introspectSchema, listSchemas } from "./introspection.mjs";
+//#region src/introspect/DataBrowser.ts
+/** How long an introspected schema is reused before it is read again. */
+const SCHEMA_TTL_MS = 6e4;
+const MAX_PAGE_SIZE = 100;
+/**
+* Reads a Postgres database's structure and pages through its rows, read-only.
+*
+* @example
+* ```typescript
+* const browser = new DataBrowser({ db });
+*
+* const { tables } = await browser.getSchema();
+* const page = await browser.query({ table: 'users', pageSize: 20 });
+* const next = await browser.query({ table: 'users', cursor: page.nextCursor });
+* ```
+*/
+var DataBrowser = class {
+	db;
+	schemas;
+	cursor;
+	tableCursors;
+	excludeTables;
+	defaultPageSize;
+	schemaCache;
+	constructor(options) {
+		this.db = options.db;
+		this.schemas = options.schemas ?? ["public"];
+		this.cursor = options.cursor;
+		this.tableCursors = options.tableCursors ?? {};
+		this.excludeTables = options.excludeTables ?? [];
+		this.defaultPageSize = options.defaultPageSize ?? 50;
+	}
+	/** Every schema the database has, browsable or not. */
+	listSchemas() {
+		return listSchemas(this.db);
+	}
+	/**
+	* The browsable tables. Cached for a minute, since a migration is rare and
+	* introspection is several catalog queries per table.
+	*/
+	async getSchema(forceRefresh = false) {
+		const now = Date.now();
+		if (!forceRefresh && this.schemaCache && now < this.schemaCache.expires) return this.schemaCache.info;
+		const info = await introspectSchema(this.db, {
+			schemas: this.schemas,
+			excludeTables: this.excludeTables
+		});
+		this.schemaCache = {
+			info,
+			expires: now + SCHEMA_TTL_MS
+		};
+		return info;
+	}
+	/** One table, or null when it is not browsable. */
+	async getTableInfo(tableName, schema = this.schemas[0] ?? "public") {
+		const { tables } = await this.getSchema();
+		return tables.find((t) => t.name === tableName && t.schema === schema) ?? null;
+	}
+	/**
+	* A page of a table's rows, filtered and sorted.
+	*
+	* @throws {TableNotFound} the table is not browsable
+	* @throws {ColumnNotFound} a filter or sort names a column it does not have
+	* @throws {UnsupportedFilterOperator} a filter's operator does not apply
+	* @throws {InvalidCursor} the cursor did not come from a previous page
+	*/
+	async query(options) {
+		const schema = options.schema ?? this.schemas[0] ?? "public";
+		const table = await this.getTableInfo(options.table, schema);
+		if (!table) throw new TableNotFound(options.table, schema);
+		const cursor = this.getCursorConfig(table);
+		const pageSize = Math.min(options.pageSize ?? this.defaultPageSize, MAX_PAGE_SIZE);
+		let query = this.db.withSchema(schema).selectFrom(table.name).selectAll();
+		if (options.filters?.length) query = applyFilters(query, options.filters, table);
+		if (options.sort?.length) query = applySorting(query, options.sort, table);
+		else if (cursor) query = query.orderBy(cursor.field, cursor.direction);
+		if (options.cursor && cursor) {
+			const after = decodeCursor(options.cursor);
+			const operator = cursor.direction === "asc" ? ">" : "<";
+			query = query.where(cursor.field, operator, after);
+		}
+		const rows = await query.limit(pageSize + 1).execute();
+		const hasMore = rows.length > pageSize;
+		const page = hasMore ? rows.slice(0, pageSize) : rows;
+		const last = page[page.length - 1];
+		const first = page[0];
+		return {
+			rows: page,
+			hasMore,
+			nextCursor: hasMore && cursor && last ? encodeCursor(last[cursor.field]) : null,
+			prevCursor: options.cursor && cursor && first ? encodeCursor(first[cursor.field]) : null
+		};
+	}
+	/**
+	* The cursor a table pages by: its own, the default, or its primary key
+	* when that is one column. Undefined means the table has nothing unique to
+	* page by, so it is read a page at a time with no next cursor.
+	*/
+	getCursorConfig(table) {
+		const configured = this.tableCursors[table.name] ?? this.cursor;
+		if (configured) return configured;
+		const [key, ...rest] = table.primaryKey;
+		if (key && rest.length === 0) return {
+			field: key,
+			direction: "asc"
+		};
+	}
+};
+//#endregion
+export { DataBrowser };
+
+//# sourceMappingURL=DataBrowser.mjs.map

package/dist/introspect/DataBrowser.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"DataBrowser.mjs","names":[],"sources":["../../src/introspect/DataBrowser.ts"],"sourcesContent":["import type { Kysely, SelectQueryBuilder } from 'kysely';\nimport { Direction, decodeCursor, encodeCursor } from '../pagination';\nimport { TableNotFound } from './errors';\nimport { applyFilters, applySorting } from './filtering';\nimport { introspectSchema, listSchemas } from './introspection';\nimport type {\n\tCursorConfig,\n\tDataBrowserOptions,\n\tQueryOptions,\n\tQueryResult,\n\tSchemaInfo,\n\tTableInfo,\n} from './types';\n\n/** How long an introspected schema is reused before it is read again. */\nconst SCHEMA_TTL_MS = 60 * 1000;\nconst MAX_PAGE_SIZE = 100;\n\n/**\n * Reads a Postgres database's structure and pages through its rows, read-only.\n *\n * @example\n * ```typescript\n * const browser = new DataBrowser({ db });\n *\n * const { tables } = await browser.getSchema();\n * const page = await browser.query({ table: 'users', pageSize: 20 });\n * const next = await browser.query({ table: 'users', cursor: page.nextCursor });\n * ```\n */\nexport class DataBrowser<DB = unknown> {\n\treadonly db: Kysely<DB>;\n\treadonly schemas: string[];\n\tprivate readonly cursor?: CursorConfig;\n\tprivate readonly tableCursors: Record<string, CursorConfig>;\n\tprivate readonly excludeTables: string[];\n\tprivate readonly defaultPageSize: number;\n\tprivate schemaCache?: { info: SchemaInfo; expires: number };\n\n\tconstructor(options: DataBrowserOptions<DB>) {\n\t\tthis.db = options.db;\n\t\tthis.schemas = options.schemas ?? ['public'];\n\t\tthis.cursor = options.cursor;\n\t\tthis.tableCursors = options.tableCursors ?? {};\n\t\tthis.excludeTables = options.excludeTables ?? [];\n\t\tthis.defaultPageSize = options.defaultPageSize ?? 50;\n\t}\n\n\t/** Every schema the database has, browsable or not. */\n\tlistSchemas(): Promise<string[]> {\n\t\treturn listSchemas(this.db);\n\t}\n\n\t/**\n\t * The browsable tables. Cached for a minute, since a migration is rare and\n\t * introspection is several catalog queries per table.\n\t */\n\tasync getSchema(forceRefresh = false): Promise<SchemaInfo> {\n\t\tconst now = Date.now();\n\t\tif (!forceRefresh && this.schemaCache && now < this.schemaCache.expires) {\n\t\t\treturn this.schemaCache.info;\n\t\t}\n\n\t\tconst info = await introspectSchema(this.db, {\n\t\t\tschemas: this.schemas,\n\t\t\texcludeTables: this.excludeTables,\n\t\t});\n\t\tthis.schemaCache = { info, expires: now + SCHEMA_TTL_MS };\n\t\treturn info;\n\t}\n\n\t/** One table, or null when it is not browsable. */\n\tasync getTableInfo(\n\t\ttableName: string,\n\t\tschema = this.schemas[0] ?? 'public',\n\t): Promise<TableInfo | null> {\n\t\tconst { tables } = await this.getSchema();\n\t\treturn (\n\t\t\ttables.find((t) => t.name === tableName && t.schema === schema) ?? null\n\t\t);\n\t}\n\n\t/**\n\t * A page of a table's rows, filtered and sorted.\n\t *\n\t * @throws {TableNotFound} the table is not browsable\n\t * @throws {ColumnNotFound} a filter or sort names a column it does not have\n\t * @throws {UnsupportedFilterOperator} a filter's operator does not apply\n\t * @throws {InvalidCursor} the cursor did not come from a previous page\n\t */\n\tasync query(options: QueryOptions): Promise<QueryResult> {\n\t\tconst schema = options.schema ?? this.schemas[0] ?? 'public';\n\t\tconst table = await this.getTableInfo(options.table, schema);\n\t\tif (!table) {\n\t\t\tthrow new TableNotFound(options.table, schema);\n\t\t}\n\n\t\tconst cursor = this.getCursorConfig(table);\n\t\tconst pageSize = Math.min(\n\t\t\toptions.pageSize ?? this.defaultPageSize,\n\t\t\tMAX_PAGE_SIZE,\n\t\t);\n\n\t\t// The table was found by introspection; the query's static types only\n\t\t// know the tables the application declared.\n\t\tlet query = (this.db as Kysely<any>)\n\t\t\t.withSchema(schema)\n\t\t\t.selectFrom(table.name)\n\t\t\t.selectAll() as SelectQueryBuilder<any, any, Record<string, unknown>>;\n\n\t\tif (options.filters?.length) {\n\t\t\tquery = applyFilters(query, options.filters, table);\n\t\t}\n\n\t\tif (options.sort?.length) {\n\t\t\tquery = applySorting(query, options.sort, table);\n\t\t} else if (cursor) {\n\t\t\tquery = query.orderBy(cursor.field, cursor.direction);\n\t\t}\n\n\t\tif (options.cursor && cursor) {\n\t\t\tconst after = decodeCursor(options.cursor);\n\t\t\tconst operator = cursor.direction === Direction.Asc ? '>' : '<';\n\t\t\tquery = query.where(cursor.field, operator, after);\n\t\t}\n\n\t\t// One more row than the page, so whether there is a next page is known\n\t\t// without counting.\n\t\tconst rows = await query.limit(pageSize + 1).execute();\n\t\tconst hasMore = rows.length > pageSize;\n\t\tconst page = hasMore ? rows.slice(0, pageSize) : rows;\n\n\t\tconst last = page[page.length - 1];\n\t\tconst first = page[0];\n\n\t\treturn {\n\t\t\trows: page,\n\t\t\thasMore,\n\t\t\tnextCursor:\n\t\t\t\thasMore && cursor && last ? encodeCursor(last[cursor.field]) : null,\n\t\t\t// Only known to exist when this page was reached through a cursor.\n\t\t\tprevCursor:\n\t\t\t\toptions.cursor && cursor && first\n\t\t\t\t\t? encodeCursor(first[cursor.field])\n\t\t\t\t\t: null,\n\t\t};\n\t}\n\n\t/**\n\t * The cursor a table pages by: its own, the default, or its primary key\n\t * when that is one column. Undefined means the table has nothing unique to\n\t * page by, so it is read a page at a time with no next cursor.\n\t */\n\tgetCursorConfig(table: TableInfo): CursorConfig | undefined {\n\t\tconst configured = this.tableCursors[table.name] ?? this.cursor;\n\t\tif (configured) return configured;\n\n\t\tconst [key, ...rest] = table.primaryKey;\n\t\tif (key && rest.length === 0) {\n\t\t\treturn { field: key, direction: Direction.Asc };\n\t\t}\n\n\t\treturn undefined;\n\t}\n}\n"],"mappings":";;;;;;AAeA,MAAM,gBAAgB;AACtB,MAAM,gBAAgB;;;;;;;;;;;;;AActB,IAAa,cAAb,MAAuC;CACtC;CACA;CACA;CACA;CACA;CACA;CACA;CAEA,YAAY,SAAiC;EAC5C,KAAK,KAAK,QAAQ;EAClB,KAAK,UAAU,QAAQ,WAAW,CAAC,QAAQ;EAC3C,KAAK,SAAS,QAAQ;EACtB,KAAK,eAAe,QAAQ,gBAAgB,CAAC;EAC7C,KAAK,gBAAgB,QAAQ,iBAAiB,CAAC;EAC/C,KAAK,kBAAkB,QAAQ,mBAAmB;CACnD;;CAGA,cAAiC;EAChC,OAAO,YAAY,KAAK,EAAE;CAC3B;;;;;CAMA,MAAM,UAAU,eAAe,OAA4B;EAC1D,MAAM,MAAM,KAAK,IAAI;EACrB,IAAI,CAAC,gBAAgB,KAAK,eAAe,MAAM,KAAK,YAAY,SAC/D,OAAO,KAAK,YAAY;EAGzB,MAAM,OAAO,MAAM,iBAAiB,KAAK,IAAI;GAC5C,SAAS,KAAK;GACd,eAAe,KAAK;EACrB,CAAC;EACD,KAAK,cAAc;GAAE;GAAM,SAAS,MAAM;EAAc;EACxD,OAAO;CACR;;CAGA,MAAM,aACL,WACA,SAAS,KAAK,QAAQ,MAAM,UACA;EAC5B,MAAM,EAAE,WAAW,MAAM,KAAK,UAAU;EACxC,OACC,OAAO,MAAM,MAAM,EAAE,SAAS,aAAa,EAAE,WAAW,MAAM,KAAK;CAErE;;;;;;;;;CAUA,MAAM,MAAM,SAA6C;EACxD,MAAM,SAAS,QAAQ,UAAU,KAAK,QAAQ,MAAM;EACpD,MAAM,QAAQ,MAAM,KAAK,aAAa,QAAQ,OAAO,MAAM;EAC3D,IAAI,CAAC,OACJ,MAAM,IAAI,cAAc,QAAQ,OAAO,MAAM;EAG9C,MAAM,SAAS,KAAK,gBAAgB,KAAK;EACzC,MAAM,WAAW,KAAK,IACrB,QAAQ,YAAY,KAAK,iBACzB,aACD;EAIA,IAAI,QAAS,KAAK,GAChB,WAAW,MAAM,CAAC,CAClB,WAAW,MAAM,IAAI,CAAC,CACtB,UAAU;EAEZ,IAAI,QAAQ,SAAS,QACpB,QAAQ,aAAa,OAAO,QAAQ,SAAS,KAAK;EAGnD,IAAI,QAAQ,MAAM,QACjB,QAAQ,aAAa,OAAO,QAAQ,MAAM,KAAK;OACzC,IAAI,QACV,QAAQ,MAAM,QAAQ,OAAO,OAAO,OAAO,SAAS;EAGrD,IAAI,QAAQ,UAAU,QAAQ;GAC7B,MAAM,QAAQ,aAAa,QAAQ,MAAM;GACzC,MAAM,WAAW,OAAO,cAAA,QAA8B,MAAM;GAC5D,QAAQ,MAAM,MAAM,OAAO,OAAO,UAAU,KAAK;EAClD;EAIA,MAAM,OAAO,MAAM,MAAM,MAAM,WAAW,CAAC,CAAC,CAAC,QAAQ;EACrD,MAAM,UAAU,KAAK,SAAS;EAC9B,MAAM,OAAO,UAAU,KAAK,MAAM,GAAG,QAAQ,IAAI;EAEjD,MAAM,OAAO,KAAK,KAAK,SAAS;EAChC,MAAM,QAAQ,KAAK;EAEnB,OAAO;GACN,MAAM;GACN;GACA,YACC,WAAW,UAAU,OAAO,aAAa,KAAK,OAAO,MAAM,IAAI;GAEhE,YACC,QAAQ,UAAU,UAAU,QACzB,aAAa,MAAM,OAAO,MAAM,IAChC;EACL;CACD;;;;;;CAOA,gBAAgB,OAA4C;EAC3D,MAAM,aAAa,KAAK,aAAa,MAAM,SAAS,KAAK;EACzD,IAAI,YAAY,OAAO;EAEvB,MAAM,CAAC,KAAK,GAAG,QAAQ,MAAM;EAC7B,IAAI,OAAO,KAAK,WAAW,GAC1B,OAAO;GAAE,OAAO;GAAK,WAAA;EAAyB;CAIhD;AACD"}

package/dist/introspect/errors.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/introspect/errors.ts
+/**
+* What a row query can get wrong. Each is the caller's mistake rather than the
+* database's, so the JSON handler answers them as 4xx with the class name as
+* the error code — a client matches on that, not on the message.
+*/
+/** A table that is not in the browsable schemas, or was excluded. */
+var TableNotFound = class extends Error {
+	table;
+	schema;
+	constructor(table, schema) {
+		super(`There is no table '${table}' in schema '${schema}'. List the tables to see what can be browsed; an excluded table is left out on purpose.`);
+		this.table = table;
+		this.schema = schema;
+		this.name = "TableNotFound";
+	}
+};
+/** A filter or sort naming a column the table does not have. */
+var ColumnNotFound = class extends Error {
+	column;
+	table;
+	constructor(column, table) {
+		super(`Table '${table}' has no column '${column}'. Use a column name exactly as the table description lists it.`);
+		this.column = column;
+		this.table = table;
+		this.name = "ColumnNotFound";
+	}
+};
+/** A filter operator that does not apply to the column's type. */
+var UnsupportedFilterOperator = class extends Error {
+	operator;
+	column;
+	columnType;
+	constructor(operator, column, columnType) {
+		super(`'${operator}' cannot filter '${column}', a ${columnType} column. Use an operator that applies to ${columnType} values.`);
+		this.operator = operator;
+		this.column = column;
+		this.columnType = columnType;
+		this.name = "UnsupportedFilterOperator";
+	}
+};
+//#endregion
+exports.ColumnNotFound = ColumnNotFound;
+exports.TableNotFound = TableNotFound;
+exports.UnsupportedFilterOperator = UnsupportedFilterOperator;
+
+//# sourceMappingURL=errors.cjs.map

package/dist/introspect/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","names":[],"sources":["../../src/introspect/errors.ts"],"sourcesContent":["/**\n * What a row query can get wrong. Each is the caller's mistake rather than the\n * database's, so the JSON handler answers them as 4xx with the class name as\n * the error code — a client matches on that, not on the message.\n */\n\n/** A table that is not in the browsable schemas, or was excluded. */\nexport class TableNotFound extends Error {\n\tconstructor(\n\t\treadonly table: string,\n\t\treadonly schema: string,\n\t) {\n\t\tsuper(\n\t\t\t`There is no table '${table}' in schema '${schema}'. List the tables to see what can be browsed; an excluded table is left out on purpose.`,\n\t\t);\n\t\tthis.name = 'TableNotFound';\n\t}\n}\n\n/** A filter or sort naming a column the table does not have. */\nexport class ColumnNotFound extends Error {\n\tconstructor(\n\t\treadonly column: string,\n\t\treadonly table: string,\n\t) {\n\t\tsuper(\n\t\t\t`Table '${table}' has no column '${column}'. Use a column name exactly as the table description lists it.`,\n\t\t);\n\t\tthis.name = 'ColumnNotFound';\n\t}\n}\n\n/** A filter operator that does not apply to the column's type. */\nexport class UnsupportedFilterOperator extends Error {\n\tconstructor(\n\t\treadonly operator: string,\n\t\treadonly column: string,\n\t\treadonly columnType: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${operator}' cannot filter '${column}', a ${columnType} column. Use an operator that applies to ${columnType} values.`,\n\t\t);\n\t\tthis.name = 'UnsupportedFilterOperator';\n\t}\n}\n"],"mappings":";;;;;;;;AAOA,IAAa,gBAAb,cAAmC,MAAM;CAE9B;CACA;CAFV,YACC,OACA,QACC;EACD,MACC,sBAAsB,MAAM,eAAe,OAAO,yFACnD;EALS,KAAA,QAAA;EACA,KAAA,SAAA;EAKT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,iBAAb,cAAoC,MAAM;CAE/B;CACA;CAFV,YACC,QACA,OACC;EACD,MACC,UAAU,MAAM,mBAAmB,OAAO,gEAC3C;EALS,KAAA,SAAA;EACA,KAAA,QAAA;EAKT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,4BAAb,cAA+C,MAAM;CAE1C;CACA;CACA;CAHV,YACC,UACA,QACA,YACC;EACD,MACC,IAAI,SAAS,mBAAmB,OAAO,OAAO,WAAW,2CAA2C,WAAW,SAChH;EANS,KAAA,WAAA;EACA,KAAA,SAAA;EACA,KAAA,aAAA;EAKT,KAAK,OAAO;CACb;AACD"}

package/dist/introspect/errors.d.cts

@@ -0,0 +1,27 @@
+//#region src/introspect/errors.d.ts
+/**
+ * What a row query can get wrong. Each is the caller's mistake rather than the
+ * database's, so the JSON handler answers them as 4xx with the class name as
+ * the error code — a client matches on that, not on the message.
+ */
+/** A table that is not in the browsable schemas, or was excluded. */
+export declare class TableNotFound extends Error {
+  readonly table: string;
+  readonly schema: string;
+  constructor(table: string, schema: string);
+}
+/** A filter or sort naming a column the table does not have. */
+export declare class ColumnNotFound extends Error {
+  readonly column: string;
+  readonly table: string;
+  constructor(column: string, table: string);
+}
+/** A filter operator that does not apply to the column's type. */
+export declare class UnsupportedFilterOperator extends Error {
+  readonly operator: string;
+  readonly column: string;
+  readonly columnType: string;
+  constructor(operator: string, column: string, columnType: string);
+}
+//#endregion
+//# sourceMappingURL=errors.d.cts.map

package/dist/introspect/errors.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.cts","names":[],"sources":["../../src/introspect/errors.ts"],"mappings":";;;;;;;qBAOa,sBAAsB;WAExB;WACA;EAFV,YACU,eACA;;;qBAUE,uBAAuB;WAEzB;WACA;EAFV,YACU,gBACA;;;qBAUE,kCAAkC;WAEpC;WACA;WACA;EAHV,YACU,kBACA,gBACA"}

package/dist/introspect/errors.d.mts

@@ -0,0 +1,27 @@
+//#region src/introspect/errors.d.ts
+/**
+ * What a row query can get wrong. Each is the caller's mistake rather than the
+ * database's, so the JSON handler answers them as 4xx with the class name as
+ * the error code — a client matches on that, not on the message.
+ */
+/** A table that is not in the browsable schemas, or was excluded. */
+export declare class TableNotFound extends Error {
+  readonly table: string;
+  readonly schema: string;
+  constructor(table: string, schema: string);
+}
+/** A filter or sort naming a column the table does not have. */
+export declare class ColumnNotFound extends Error {
+  readonly column: string;
+  readonly table: string;
+  constructor(column: string, table: string);
+}
+/** A filter operator that does not apply to the column's type. */
+export declare class UnsupportedFilterOperator extends Error {
+  readonly operator: string;
+  readonly column: string;
+  readonly columnType: string;
+  constructor(operator: string, column: string, columnType: string);
+}
+//#endregion
+//# sourceMappingURL=errors.d.mts.map

package/dist/introspect/errors.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.mts","names":[],"sources":["../../src/introspect/errors.ts"],"mappings":";;;;;;;qBAOa,sBAAsB;WAExB;WACA;EAFV,YACU,eACA;;;qBAUE,uBAAuB;WAEzB;WACA;EAFV,YACU,gBACA;;;qBAUE,kCAAkC;WAEpC;WACA;WACA;EAHV,YACU,kBACA,gBACA"}

package/dist/introspect/errors.mjs

@@ -0,0 +1,45 @@
+//#region src/introspect/errors.ts
+/**
+* What a row query can get wrong. Each is the caller's mistake rather than the
+* database's, so the JSON handler answers them as 4xx with the class name as
+* the error code — a client matches on that, not on the message.
+*/
+/** A table that is not in the browsable schemas, or was excluded. */
+var TableNotFound = class extends Error {
+	table;
+	schema;
+	constructor(table, schema) {
+		super(`There is no table '${table}' in schema '${schema}'. List the tables to see what can be browsed; an excluded table is left out on purpose.`);
+		this.table = table;
+		this.schema = schema;
+		this.name = "TableNotFound";
+	}
+};
+/** A filter or sort naming a column the table does not have. */
+var ColumnNotFound = class extends Error {
+	column;
+	table;
+	constructor(column, table) {
+		super(`Table '${table}' has no column '${column}'. Use a column name exactly as the table description lists it.`);
+		this.column = column;
+		this.table = table;
+		this.name = "ColumnNotFound";
+	}
+};
+/** A filter operator that does not apply to the column's type. */
+var UnsupportedFilterOperator = class extends Error {
+	operator;
+	column;
+	columnType;
+	constructor(operator, column, columnType) {
+		super(`'${operator}' cannot filter '${column}', a ${columnType} column. Use an operator that applies to ${columnType} values.`);
+		this.operator = operator;
+		this.column = column;
+		this.columnType = columnType;
+		this.name = "UnsupportedFilterOperator";
+	}
+};
+//#endregion
+export { ColumnNotFound, TableNotFound, UnsupportedFilterOperator };
+
+//# sourceMappingURL=errors.mjs.map

package/dist/introspect/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../../src/introspect/errors.ts"],"sourcesContent":["/**\n * What a row query can get wrong. Each is the caller's mistake rather than the\n * database's, so the JSON handler answers them as 4xx with the class name as\n * the error code — a client matches on that, not on the message.\n */\n\n/** A table that is not in the browsable schemas, or was excluded. */\nexport class TableNotFound extends Error {\n\tconstructor(\n\t\treadonly table: string,\n\t\treadonly schema: string,\n\t) {\n\t\tsuper(\n\t\t\t`There is no table '${table}' in schema '${schema}'. List the tables to see what can be browsed; an excluded table is left out on purpose.`,\n\t\t);\n\t\tthis.name = 'TableNotFound';\n\t}\n}\n\n/** A filter or sort naming a column the table does not have. */\nexport class ColumnNotFound extends Error {\n\tconstructor(\n\t\treadonly column: string,\n\t\treadonly table: string,\n\t) {\n\t\tsuper(\n\t\t\t`Table '${table}' has no column '${column}'. Use a column name exactly as the table description lists it.`,\n\t\t);\n\t\tthis.name = 'ColumnNotFound';\n\t}\n}\n\n/** A filter operator that does not apply to the column's type. */\nexport class UnsupportedFilterOperator extends Error {\n\tconstructor(\n\t\treadonly operator: string,\n\t\treadonly column: string,\n\t\treadonly columnType: string,\n\t) {\n\t\tsuper(\n\t\t\t`'${operator}' cannot filter '${column}', a ${columnType} column. Use an operator that applies to ${columnType} values.`,\n\t\t);\n\t\tthis.name = 'UnsupportedFilterOperator';\n\t}\n}\n"],"mappings":";;;;;;;AAOA,IAAa,gBAAb,cAAmC,MAAM;CAE9B;CACA;CAFV,YACC,OACA,QACC;EACD,MACC,sBAAsB,MAAM,eAAe,OAAO,yFACnD;EALS,KAAA,QAAA;EACA,KAAA,SAAA;EAKT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,iBAAb,cAAoC,MAAM;CAE/B;CACA;CAFV,YACC,QACA,OACC;EACD,MACC,UAAU,MAAM,mBAAmB,OAAO,gEAC3C;EALS,KAAA,SAAA;EACA,KAAA,QAAA;EAKT,KAAK,OAAO;CACb;AACD;;AAGA,IAAa,4BAAb,cAA+C,MAAM;CAE1C;CACA;CACA;CAHV,YACC,UACA,QACA,YACC;EACD,MACC,IAAI,SAAS,mBAAmB,OAAO,OAAO,WAAW,2CAA2C,WAAW,SAChH;EANS,KAAA,WAAA;EACA,KAAA,SAAA;EACA,KAAA,aAAA;EAKT,KAAK,OAAO;CACb;AACD"}