@geekmidas/db 10.0.0-alpha.1 → 10.0.0-alpha.100

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.cjs

@@ -1,6 +1,73 @@
-const require_errors = require('./errors-Cs5jlAv-.cjs');
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/errors.ts
+/**
+* Database URL errors and redaction — engine-neutral.
+*
+* Nothing here is Postgres-specific: every engine addresses itself as a URL
+* carrying a password, and "must name a host" holds for all of them. The parts
+* that differ — libpq's `options=-c search_path=…`, which no other engine
+* accepts — live under the driver they belong to.
+*
+* Messages state the rule, which is constant; the offending value is a field.
+* An interpolated message cannot be matched on and carries user input into
+* every log line that touches it.
+*/
+/**
+* Replace the password in a connection string with `***`.
+*
+* A connection string is a secret, and the places it is most likely to be
+* written down — a log line, an error, a crash report shipped to a third party
+* — are the places nobody is reading carefully. This exists so that redacting
+* is the easy thing to do at each of them.
+*
+* Safe on input that is not a URL: it returns a constant rather than throwing,
+* because this runs on paths that must not fail. Anything unparseable is
+* treated as potentially secret and withheld entirely rather than echoed.
+*/
+function redactDatabaseUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!parsed.password) return url;
+		parsed.password = "***";
+		return parsed.toString();
+	} catch {
+		return "<unparseable url>";
+	}
+}
+/**
+* Base for an address that cannot become a connection string.
+*
+* Deliberately carries no URL field: these are thrown while *composing* one, so
+* there is no URL yet — only the parts, which include the password.
+*/
+var DatabaseAddressError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = new.target.name;
+	}
+};
+/** An address with no host to connect to. */
+var MissingDatabaseHost = class extends DatabaseAddressError {
+	constructor() {
+		super("A database address must name a host");
+	}
+};
+/**
+* An address with no database name.
+*
+* Postgres silently falls back to the connecting role's name, so the app
+* connects successfully to the wrong database and fails later with confusing
+* "relation does not exist" errors. Rejecting it here is much cheaper.
+*/
+var MissingDatabaseName = class extends DatabaseAddressError {
+	constructor() {
+		super("A database address must name a database");
+	}
+};
+//#endregion
+exports.DatabaseAddressError = DatabaseAddressError;
+exports.MissingDatabaseHost = MissingDatabaseHost;
+exports.MissingDatabaseName = MissingDatabaseName;
+exports.redactDatabaseUrl = redactDatabaseUrl;
 
-exports.DatabaseAddressError = require_errors.DatabaseAddressError;
-exports.MissingDatabaseHost = require_errors.MissingDatabaseHost;
-exports.MissingDatabaseName = require_errors.MissingDatabaseName;
-exports.redactDatabaseUrl = require_errors.redactDatabaseUrl;
+//# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Database URL errors and redaction — engine-neutral.\n *\n * Nothing here is Postgres-specific: every engine addresses itself as a URL\n * carrying a password, and \"must name a host\" holds for all of them. The parts\n * that differ — libpq's `options=-c search_path=…`, which no other engine\n * accepts — live under the driver they belong to.\n *\n * Messages state the rule, which is constant; the offending value is a field.\n * An interpolated message cannot be matched on and carries user input into\n * every log line that touches it.\n */\n\n/**\n * Replace the password in a connection string with `***`.\n *\n * A connection string is a secret, and the places it is most likely to be\n * written down — a log line, an error, a crash report shipped to a third party\n * — are the places nobody is reading carefully. This exists so that redacting\n * is the easy thing to do at each of them.\n *\n * Safe on input that is not a URL: it returns a constant rather than throwing,\n * because this runs on paths that must not fail. Anything unparseable is\n * treated as potentially secret and withheld entirely rather than echoed.\n */\nexport function redactDatabaseUrl(url: string): string {\n\ttry {\n\t\tconst parsed = new URL(url);\n\t\tif (!parsed.password) return url;\n\t\tparsed.password = '***';\n\t\treturn parsed.toString();\n\t} catch {\n\t\treturn '<unparseable url>';\n\t}\n}\n\n/**\n * Base for an address that cannot become a connection string.\n *\n * Deliberately carries no URL field: these are thrown while *composing* one, so\n * there is no URL yet — only the parts, which include the password.\n */\nexport abstract class DatabaseAddressError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = new.target.name;\n\t}\n}\n\n/** An address with no host to connect to. */\nexport class MissingDatabaseHost extends DatabaseAddressError {\n\tconstructor() {\n\t\tsuper('A database address must name a host');\n\t}\n}\n\n/**\n * An address with no database name.\n *\n * Postgres silently falls back to the connecting role's name, so the app\n * connects successfully to the wrong database and fails later with confusing\n * \"relation does not exist\" errors. Rejecting it here is much cheaper.\n */\nexport class MissingDatabaseName extends DatabaseAddressError {\n\tconstructor() {\n\t\tsuper('A database address must name a database');\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBAAkB,KAAqB;CACtD,IAAI;EACH,MAAM,SAAS,IAAI,IAAI,GAAG;EAC1B,IAAI,CAAC,OAAO,UAAU,OAAO;EAC7B,OAAO,WAAW;EAClB,OAAO,OAAO,SAAS;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;;AAQA,IAAsB,uBAAtB,cAAmD,MAAM;CACxD,YAAY,SAAiB;EAC5B,MAAM,OAAO;EACb,KAAK,OAAO,WAAW;CACxB;AACD;;AAGA,IAAa,sBAAb,cAAyC,qBAAqB;CAC7D,cAAc;EACb,MAAM,qCAAqC;CAC5C;AACD;;;;;;;;AASA,IAAa,sBAAb,cAAyC,qBAAqB;CAC7D,cAAc;EACb,MAAM,yCAAyC;CAChD;AACD"}

package/dist/errors.d.cts

@@ -23,18 +23,18 @@
  * because this runs on paths that must not fail. Anything unparseable is
  * treated as potentially secret and withheld entirely rather than echoed.
  */
-declare function redactDatabaseUrl(url: string): string;
+export declare function redactDatabaseUrl(url: string): string;
 /**
  * Base for an address that cannot become a connection string.
  *
  * Deliberately carries no URL field: these are thrown while *composing* one, so
  * there is no URL yet — only the parts, which include the password.
  */
-declare abstract class DatabaseAddressError extends Error {
+export declare abstract class DatabaseAddressError extends Error {
   constructor(message: string);
 }
 /** An address with no host to connect to. */
-declare class MissingDatabaseHost extends DatabaseAddressError {
+export declare class MissingDatabaseHost extends DatabaseAddressError {
   constructor();
 }
 /**
@@ -44,10 +44,8 @@ declare class MissingDatabaseHost extends DatabaseAddressError {
  * connects successfully to the wrong database and fails later with confusing
  * "relation does not exist" errors. Rejecting it here is much cheaper.
  */
-declare class MissingDatabaseName extends DatabaseAddressError {
+export declare class MissingDatabaseName extends DatabaseAddressError {
   constructor();
 }
-//# sourceMappingURL=errors.d.ts.map
 //#endregion
-export { DatabaseAddressError, MissingDatabaseHost, MissingDatabaseName, redactDatabaseUrl };
 //# sourceMappingURL=errors.d.cts.map

package/dist/errors.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.cts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;AAyBA;AAiBA;AAQA;AAaA;;;;;;;;;;;;;;;;;;;;iBAtCgB,iBAAA;;;;;;;uBAiBM,oBAAA,SAA6B,KAAK;;;;cAQ3C,mBAAA,SAA4B,oBAAoB;;;;;;;;;;cAahD,mBAAA,SAA4B,oBAAoB"}
+{"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

@@ -23,18 +23,18 @@
  * because this runs on paths that must not fail. Anything unparseable is
  * treated as potentially secret and withheld entirely rather than echoed.
  */
-declare function redactDatabaseUrl(url: string): string;
+export declare function redactDatabaseUrl(url: string): string;
 /**
  * Base for an address that cannot become a connection string.
  *
  * Deliberately carries no URL field: these are thrown while *composing* one, so
  * there is no URL yet — only the parts, which include the password.
  */
-declare abstract class DatabaseAddressError extends Error {
+export declare abstract class DatabaseAddressError extends Error {
   constructor(message: string);
 }
 /** An address with no host to connect to. */
-declare class MissingDatabaseHost extends DatabaseAddressError {
+export declare class MissingDatabaseHost extends DatabaseAddressError {
   constructor();
 }
 /**
@@ -44,10 +44,8 @@ declare class MissingDatabaseHost extends DatabaseAddressError {
  * connects successfully to the wrong database and fails later with confusing
  * "relation does not exist" errors. Rejecting it here is much cheaper.
  */
-declare class MissingDatabaseName extends DatabaseAddressError {
+export declare class MissingDatabaseName extends DatabaseAddressError {
   constructor();
 }
-//# sourceMappingURL=errors.d.ts.map
 //#endregion
-export { DatabaseAddressError, MissingDatabaseHost, MissingDatabaseName, redactDatabaseUrl };
 //# sourceMappingURL=errors.d.mts.map

package/dist/errors.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.mts","names":[],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;AAyBA;AAiBA;AAQA;AAaA;;;;;;;;;;;;;;;;;;;;iBAtCgB,iBAAA;;;;;;;uBAiBM,oBAAA,SAA6B,KAAK;;;;cAQ3C,mBAAA,SAA4B,oBAAoB;;;;;;;;;;cAahD,mBAAA,SAA4B,oBAAoB"}
+{"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/errors.mjs

@@ -1,3 +1,69 @@
-import { DatabaseAddressError, MissingDatabaseHost, MissingDatabaseName, redactDatabaseUrl } from "./errors-CfFCan-X.mjs";
+//#region src/errors.ts
+/**
+* Database URL errors and redaction — engine-neutral.
+*
+* Nothing here is Postgres-specific: every engine addresses itself as a URL
+* carrying a password, and "must name a host" holds for all of them. The parts
+* that differ — libpq's `options=-c search_path=…`, which no other engine
+* accepts — live under the driver they belong to.
+*
+* Messages state the rule, which is constant; the offending value is a field.
+* An interpolated message cannot be matched on and carries user input into
+* every log line that touches it.
+*/
+/**
+* Replace the password in a connection string with `***`.
+*
+* A connection string is a secret, and the places it is most likely to be
+* written down — a log line, an error, a crash report shipped to a third party
+* — are the places nobody is reading carefully. This exists so that redacting
+* is the easy thing to do at each of them.
+*
+* Safe on input that is not a URL: it returns a constant rather than throwing,
+* because this runs on paths that must not fail. Anything unparseable is
+* treated as potentially secret and withheld entirely rather than echoed.
+*/
+function redactDatabaseUrl(url) {
+	try {
+		const parsed = new URL(url);
+		if (!parsed.password) return url;
+		parsed.password = "***";
+		return parsed.toString();
+	} catch {
+		return "<unparseable url>";
+	}
+}
+/**
+* Base for an address that cannot become a connection string.
+*
+* Deliberately carries no URL field: these are thrown while *composing* one, so
+* there is no URL yet — only the parts, which include the password.
+*/
+var DatabaseAddressError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = new.target.name;
+	}
+};
+/** An address with no host to connect to. */
+var MissingDatabaseHost = class extends DatabaseAddressError {
+	constructor() {
+		super("A database address must name a host");
+	}
+};
+/**
+* An address with no database name.
+*
+* Postgres silently falls back to the connecting role's name, so the app
+* connects successfully to the wrong database and fails later with confusing
+* "relation does not exist" errors. Rejecting it here is much cheaper.
+*/
+var MissingDatabaseName = class extends DatabaseAddressError {
+	constructor() {
+		super("A database address must name a database");
+	}
+};
+//#endregion
+export { DatabaseAddressError, MissingDatabaseHost, MissingDatabaseName, redactDatabaseUrl };
 
-export { DatabaseAddressError, MissingDatabaseHost, MissingDatabaseName, redactDatabaseUrl };
+//# sourceMappingURL=errors.mjs.map

package/dist/errors.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Database URL errors and redaction — engine-neutral.\n *\n * Nothing here is Postgres-specific: every engine addresses itself as a URL\n * carrying a password, and \"must name a host\" holds for all of them. The parts\n * that differ — libpq's `options=-c search_path=…`, which no other engine\n * accepts — live under the driver they belong to.\n *\n * Messages state the rule, which is constant; the offending value is a field.\n * An interpolated message cannot be matched on and carries user input into\n * every log line that touches it.\n */\n\n/**\n * Replace the password in a connection string with `***`.\n *\n * A connection string is a secret, and the places it is most likely to be\n * written down — a log line, an error, a crash report shipped to a third party\n * — are the places nobody is reading carefully. This exists so that redacting\n * is the easy thing to do at each of them.\n *\n * Safe on input that is not a URL: it returns a constant rather than throwing,\n * because this runs on paths that must not fail. Anything unparseable is\n * treated as potentially secret and withheld entirely rather than echoed.\n */\nexport function redactDatabaseUrl(url: string): string {\n\ttry {\n\t\tconst parsed = new URL(url);\n\t\tif (!parsed.password) return url;\n\t\tparsed.password = '***';\n\t\treturn parsed.toString();\n\t} catch {\n\t\treturn '<unparseable url>';\n\t}\n}\n\n/**\n * Base for an address that cannot become a connection string.\n *\n * Deliberately carries no URL field: these are thrown while *composing* one, so\n * there is no URL yet — only the parts, which include the password.\n */\nexport abstract class DatabaseAddressError extends Error {\n\tconstructor(message: string) {\n\t\tsuper(message);\n\t\tthis.name = new.target.name;\n\t}\n}\n\n/** An address with no host to connect to. */\nexport class MissingDatabaseHost extends DatabaseAddressError {\n\tconstructor() {\n\t\tsuper('A database address must name a host');\n\t}\n}\n\n/**\n * An address with no database name.\n *\n * Postgres silently falls back to the connecting role's name, so the app\n * connects successfully to the wrong database and fails later with confusing\n * \"relation does not exist\" errors. Rejecting it here is much cheaper.\n */\nexport class MissingDatabaseName extends DatabaseAddressError {\n\tconstructor() {\n\t\tsuper('A database address must name a database');\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;AAyBA,SAAgB,kBAAkB,KAAqB;CACtD,IAAI;EACH,MAAM,SAAS,IAAI,IAAI,GAAG;EAC1B,IAAI,CAAC,OAAO,UAAU,OAAO;EAC7B,OAAO,WAAW;EAClB,OAAO,OAAO,SAAS;CACxB,QAAQ;EACP,OAAO;CACR;AACD;;;;;;;AAQA,IAAsB,uBAAtB,cAAmD,MAAM;CACxD,YAAY,SAAiB;EAC5B,MAAM,OAAO;EACb,KAAK,OAAO,WAAW;CACxB;AACD;;AAGA,IAAa,sBAAb,cAAyC,qBAAqB;CAC7D,cAAc;EACb,MAAM,qCAAqC;CAC5C;AACD;;;;;;;;AASA,IAAa,sBAAb,cAAyC,qBAAqB;CAC7D,cAAc;EACb,MAAM,yCAAyC;CAChD;AACD"}

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