@geekmidas/db 10.0.0-alpha.9 → 10.0.0-alpha.91

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"}

package/dist/introspect/filtering.cjs

@@ -0,0 +1,101 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+require("../pagination.cjs");
+const require_introspect_errors = require("./errors.cjs");
+require("./types.cjs");
+//#region src/introspect/filtering.ts
+const NULLS = ["is_null", "is_not_null"];
+const EQUALITY = [
+	"eq",
+	"neq",
+	...NULLS
+];
+const ORDERED = [
+	...EQUALITY,
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+const MEMBERSHIP = ["in", "nin"];
+/** Which operators make sense for each column type. */
+const OPERATORS = {
+	string: [
+		...EQUALITY,
+		"like",
+		"ilike",
+		...MEMBERSHIP
+	],
+	number: [...ORDERED, ...MEMBERSHIP],
+	boolean: EQUALITY,
+	date: ORDERED,
+	datetime: ORDERED,
+	uuid: [...EQUALITY, ...MEMBERSHIP],
+	json: NULLS,
+	binary: NULLS,
+	unknown: EQUALITY
+};
+/**
+* Whether a filter's operator applies to the column it names.
+*/
+function validateFilter(filter, column) {
+	if (OPERATORS[column.type].includes(filter.operator)) return { valid: true };
+	return {
+		valid: false,
+		error: new require_introspect_errors.UnsupportedFilterOperator(filter.operator, column.name, column.type)
+	};
+}
+/**
+* Adds each filter to the query as a `where`, after checking the column exists
+* and the operator applies to it.
+*
+* @throws {ColumnNotFound} a filter names a column the table does not have
+* @throws {UnsupportedFilterOperator} an operator does not apply to its column
+*/
+function applyFilters(query, filters, table) {
+	let result = query;
+	for (const filter of filters) {
+		const column = table.columns.find((c) => c.name === filter.column);
+		if (!column) throw new require_introspect_errors.ColumnNotFound(filter.column, table.name);
+		const validation = validateFilter(filter, column);
+		if (!validation.valid) throw validation.error;
+		result = applyFilterCondition(result, filter);
+	}
+	return result;
+}
+function applyFilterCondition(query, filter) {
+	const column = filter.column;
+	const { value } = filter;
+	switch (filter.operator) {
+		case "eq": return query.where(column, "=", value);
+		case "neq": return query.where(column, "!=", value);
+		case "gt": return query.where(column, ">", value);
+		case "gte": return query.where(column, ">=", value);
+		case "lt": return query.where(column, "<", value);
+		case "lte": return query.where(column, "<=", value);
+		case "like": return query.where(column, "like", value);
+		case "ilike": return query.where(column, "ilike", value);
+		case "in": return query.where(column, "in", value);
+		case "nin": return query.where(column, "not in", value);
+		case "is_null": return query.where(column, "is", null);
+		case "is_not_null": return query.where(column, "is not", null);
+	}
+}
+/**
+* Adds an `order by` per sort, in the order given.
+*
+* @throws {ColumnNotFound} a sort names a column the table does not have
+*/
+function applySorting(query, sorts, table) {
+	let result = query;
+	for (const sort of sorts) {
+		if (!table.columns.some((c) => c.name === sort.column)) throw new require_introspect_errors.ColumnNotFound(sort.column, table.name);
+		result = result.orderBy(sort.column, sort.direction === "asc" ? "asc" : "desc");
+	}
+	return result;
+}
+//#endregion
+exports.applyFilters = applyFilters;
+exports.applySorting = applySorting;
+exports.validateFilter = validateFilter;
+
+//# sourceMappingURL=filtering.cjs.map

package/dist/introspect/filtering.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.cjs","names":["UnsupportedFilterOperator","ColumnNotFound"],"sources":["../../src/introspect/filtering.ts"],"sourcesContent":["import type { SelectQueryBuilder } from 'kysely';\nimport { Direction } from '../pagination';\nimport { ColumnNotFound, UnsupportedFilterOperator } from './errors';\nimport {\n\ttype ColumnInfo,\n\ttype ColumnType,\n\ttype FilterCondition,\n\tFilterOperator,\n\ttype SortConfig,\n\ttype TableInfo,\n} from './types';\n\nconst NULLS = [FilterOperator.IsNull, FilterOperator.IsNotNull];\nconst EQUALITY = [FilterOperator.Eq, FilterOperator.Neq, ...NULLS];\nconst ORDERED = [\n\t...EQUALITY,\n\tFilterOperator.Gt,\n\tFilterOperator.Gte,\n\tFilterOperator.Lt,\n\tFilterOperator.Lte,\n];\nconst MEMBERSHIP = [FilterOperator.In, FilterOperator.Nin];\n\n/** Which operators make sense for each column type. */\nconst OPERATORS: Record<ColumnType, FilterOperator[]> = {\n\tstring: [\n\t\t...EQUALITY,\n\t\tFilterOperator.Like,\n\t\tFilterOperator.Ilike,\n\t\t...MEMBERSHIP,\n\t],\n\tnumber: [...ORDERED, ...MEMBERSHIP],\n\tboolean: EQUALITY,\n\tdate: ORDERED,\n\tdatetime: ORDERED,\n\tuuid: [...EQUALITY, ...MEMBERSHIP],\n\tjson: NULLS,\n\tbinary: NULLS,\n\tunknown: EQUALITY,\n};\n\n/**\n * Whether a filter's operator applies to the column it names.\n */\nexport function validateFilter(\n\tfilter: FilterCondition,\n\tcolumn: ColumnInfo,\n): { valid: true } | { valid: false; error: UnsupportedFilterOperator } {\n\tif (OPERATORS[column.type].includes(filter.operator)) {\n\t\treturn { valid: true };\n\t}\n\n\treturn {\n\t\tvalid: false,\n\t\terror: new UnsupportedFilterOperator(\n\t\t\tfilter.operator,\n\t\t\tcolumn.name,\n\t\t\tcolumn.type,\n\t\t),\n\t};\n}\n\n/**\n * Adds each filter to the query as a `where`, after checking the column exists\n * and the operator applies to it.\n *\n * @throws {ColumnNotFound} a filter names a column the table does not have\n * @throws {UnsupportedFilterOperator} an operator does not apply to its column\n */\nexport function applyFilters<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tfilters: FilterCondition[],\n\ttable: TableInfo,\n): SelectQueryBuilder<DB, TB, O> {\n\tlet result = query;\n\n\tfor (const filter of filters) {\n\t\tconst column = table.columns.find((c) => c.name === filter.column);\n\t\tif (!column) {\n\t\t\tthrow new ColumnNotFound(filter.column, table.name);\n\t\t}\n\n\t\tconst validation = validateFilter(filter, column);\n\t\tif (!validation.valid) {\n\t\t\tthrow validation.error;\n\t\t}\n\n\t\tresult = applyFilterCondition(result, filter);\n\t}\n\n\treturn result;\n}\n\nfunction applyFilterCondition<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tfilter: FilterCondition,\n): SelectQueryBuilder<DB, TB, O> {\n\t// The column was checked against the introspected table, which the query's\n\t// static types know nothing about.\n\tconst column = filter.column as any;\n\tconst { value } = filter;\n\n\tswitch (filter.operator) {\n\t\tcase FilterOperator.Eq:\n\t\t\treturn query.where(column, '=', value);\n\t\tcase FilterOperator.Neq:\n\t\t\treturn query.where(column, '!=', value);\n\t\tcase FilterOperator.Gt:\n\t\t\treturn query.where(column, '>', value);\n\t\tcase FilterOperator.Gte:\n\t\t\treturn query.where(column, '>=', value);\n\t\tcase FilterOperator.Lt:\n\t\t\treturn query.where(column, '<', value);\n\t\tcase FilterOperator.Lte:\n\t\t\treturn query.where(column, '<=', value);\n\t\tcase FilterOperator.Like:\n\t\t\treturn query.where(column, 'like', value);\n\t\tcase FilterOperator.Ilike:\n\t\t\treturn query.where(column, 'ilike', value);\n\t\tcase FilterOperator.In:\n\t\t\treturn query.where(column, 'in', value as unknown[]);\n\t\tcase FilterOperator.Nin:\n\t\t\treturn query.where(column, 'not in', value as unknown[]);\n\t\tcase FilterOperator.IsNull:\n\t\t\treturn query.where(column, 'is', null);\n\t\tcase FilterOperator.IsNotNull:\n\t\t\treturn query.where(column, 'is not', null);\n\t}\n}\n\n/**\n * Adds an `order by` per sort, in the order given.\n *\n * @throws {ColumnNotFound} a sort names a column the table does not have\n */\nexport function applySorting<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tsorts: SortConfig[],\n\ttable: TableInfo,\n): SelectQueryBuilder<DB, TB, O> {\n\tlet result = query;\n\n\tfor (const sort of sorts) {\n\t\tif (!table.columns.some((c) => c.name === sort.column)) {\n\t\t\tthrow new ColumnNotFound(sort.column, table.name);\n\t\t}\n\n\t\tresult = result.orderBy(\n\t\t\tsort.column as any,\n\t\t\tsort.direction === Direction.Asc ? 'asc' : 'desc',\n\t\t);\n\t}\n\n\treturn result;\n}\n"],"mappings":";;;;;AAYA,MAAM,QAAQ,CAAA,WAAA,aAAgD;AAC9D,MAAM,WAAW;;;CAAwC,GAAG;AAAK;AACjE,MAAM,UAAU;CACf,GAAG;;;;;AAKJ;AACA,MAAM,aAAa,CAAA,MAAA,KAAsC;;AAGzD,MAAM,YAAkD;CACvD,QAAQ;EACP,GAAG;;;EAGH,GAAG;CACJ;CACA,QAAQ,CAAC,GAAG,SAAS,GAAG,UAAU;CAClC,SAAS;CACT,MAAM;CACN,UAAU;CACV,MAAM,CAAC,GAAG,UAAU,GAAG,UAAU;CACjC,MAAM;CACN,QAAQ;CACR,SAAS;AACV;;;;AAKA,SAAgB,eACf,QACA,QACuE;CACvE,IAAI,UAAU,OAAO,KAAK,CAAC,SAAS,OAAO,QAAQ,GAClD,OAAO,EAAE,OAAO,KAAK;CAGtB,OAAO;EACN,OAAO;EACP,OAAO,IAAIA,0BAAAA,0BACV,OAAO,UACP,OAAO,MACP,OAAO,IACR;CACD;AACD;;;;;;;;AASA,SAAgB,aACf,OACA,SACA,OACgC;CAChC,IAAI,SAAS;CAEb,KAAK,MAAM,UAAU,SAAS;EAC7B,MAAM,SAAS,MAAM,QAAQ,MAAM,MAAM,EAAE,SAAS,OAAO,MAAM;EACjE,IAAI,CAAC,QACJ,MAAM,IAAIC,0BAAAA,eAAe,OAAO,QAAQ,MAAM,IAAI;EAGnD,MAAM,aAAa,eAAe,QAAQ,MAAM;EAChD,IAAI,CAAC,WAAW,OACf,MAAM,WAAW;EAGlB,SAAS,qBAAqB,QAAQ,MAAM;CAC7C;CAEA,OAAO;AACR;AAEA,SAAS,qBACR,OACA,QACgC;CAGhC,MAAM,SAAS,OAAO;CACtB,MAAM,EAAE,UAAU;CAElB,QAAQ,OAAO,UAAf;EACC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,QACC,OAAO,MAAM,MAAM,QAAQ,QAAQ,KAAK;EACzC,KAAA,SACC,OAAO,MAAM,MAAM,QAAQ,SAAS,KAAK;EAC1C,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAkB;EACpD,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,UAAU,KAAkB;EACxD,KAAA,WACC,OAAO,MAAM,MAAM,QAAQ,MAAM,IAAI;EACtC,KAAA,eACC,OAAO,MAAM,MAAM,QAAQ,UAAU,IAAI;CAC3C;AACD;;;;;;AAOA,SAAgB,aACf,OACA,OACA,OACgC;CAChC,IAAI,SAAS;CAEb,KAAK,MAAM,QAAQ,OAAO;EACzB,IAAI,CAAC,MAAM,QAAQ,MAAM,MAAM,EAAE,SAAS,KAAK,MAAM,GACpD,MAAM,IAAIA,0BAAAA,eAAe,KAAK,QAAQ,MAAM,IAAI;EAGjD,SAAS,OAAO,QACf,KAAK,QACL,KAAK,cAAA,QAA8B,QAAQ,MAC5C;CACD;CAEA,OAAO;AACR"}

package/dist/introspect/filtering.d.cts

@@ -0,0 +1,29 @@
+import { ColumnInfo, FilterCondition, SortConfig, TableInfo } from "./types.cjs";
+import { UnsupportedFilterOperator } from "./errors.cjs";
+import { SelectQueryBuilder } from "kysely";
+//#region src/introspect/filtering.d.ts
+/**
+ * Whether a filter's operator applies to the column it names.
+ */
+export declare function validateFilter(filter: FilterCondition, column: ColumnInfo): {
+  valid: true;
+} | {
+  valid: false;
+  error: UnsupportedFilterOperator;
+};
+/**
+ * Adds each filter to the query as a `where`, after checking the column exists
+ * and the operator applies to it.
+ *
+ * @throws {ColumnNotFound} a filter names a column the table does not have
+ * @throws {UnsupportedFilterOperator} an operator does not apply to its column
+ */
+export declare function applyFilters<DB, TB extends keyof DB, O>(query: SelectQueryBuilder<DB, TB, O>, filters: FilterCondition[], table: TableInfo): SelectQueryBuilder<DB, TB, O>;
+/**
+ * Adds an `order by` per sort, in the order given.
+ *
+ * @throws {ColumnNotFound} a sort names a column the table does not have
+ */
+export declare function applySorting<DB, TB extends keyof DB, O>(query: SelectQueryBuilder<DB, TB, O>, sorts: SortConfig[], table: TableInfo): SelectQueryBuilder<DB, TB, O>;
+//#endregion
+//# sourceMappingURL=filtering.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.d.cts","names":[],"sources":["../../src/introspect/filtering.ts"],"mappings":";;;;;;;wBA4CgB,eACf,QAAQ,iBACR,QAAQ;EACJ;;EAAkB;EAAc,OAAO;;;;;;;;;wBAsB5B,aAAa,IAAI,iBAAiB,IAAI,GACrD,OAAO,mBAAmB,IAAI,IAAI,IAClC,SAAS,mBACT,OAAO,YACL,mBAAmB,IAAI,IAAI;;;;;;wBA8Dd,aAAa,IAAI,iBAAiB,IAAI,GACrD,OAAO,mBAAmB,IAAI,IAAI,IAClC,OAAO,cACP,OAAO,YACL,mBAAmB,IAAI,IAAI"}

package/dist/introspect/filtering.d.mts

@@ -0,0 +1,29 @@
+import { ColumnInfo, FilterCondition, SortConfig, TableInfo } from "./types.mjs";
+import { UnsupportedFilterOperator } from "./errors.mjs";
+import { SelectQueryBuilder } from "kysely";
+//#region src/introspect/filtering.d.ts
+/**
+ * Whether a filter's operator applies to the column it names.
+ */
+export declare function validateFilter(filter: FilterCondition, column: ColumnInfo): {
+  valid: true;
+} | {
+  valid: false;
+  error: UnsupportedFilterOperator;
+};
+/**
+ * Adds each filter to the query as a `where`, after checking the column exists
+ * and the operator applies to it.
+ *
+ * @throws {ColumnNotFound} a filter names a column the table does not have
+ * @throws {UnsupportedFilterOperator} an operator does not apply to its column
+ */
+export declare function applyFilters<DB, TB extends keyof DB, O>(query: SelectQueryBuilder<DB, TB, O>, filters: FilterCondition[], table: TableInfo): SelectQueryBuilder<DB, TB, O>;
+/**
+ * Adds an `order by` per sort, in the order given.
+ *
+ * @throws {ColumnNotFound} a sort names a column the table does not have
+ */
+export declare function applySorting<DB, TB extends keyof DB, O>(query: SelectQueryBuilder<DB, TB, O>, sorts: SortConfig[], table: TableInfo): SelectQueryBuilder<DB, TB, O>;
+//#endregion
+//# sourceMappingURL=filtering.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.d.mts","names":[],"sources":["../../src/introspect/filtering.ts"],"mappings":";;;;;;;wBA4CgB,eACf,QAAQ,iBACR,QAAQ;EACJ;;EAAkB;EAAc,OAAO;;;;;;;;;wBAsB5B,aAAa,IAAI,iBAAiB,IAAI,GACrD,OAAO,mBAAmB,IAAI,IAAI,IAClC,SAAS,mBACT,OAAO,YACL,mBAAmB,IAAI,IAAI;;;;;;wBA8Dd,aAAa,IAAI,iBAAiB,IAAI,GACrD,OAAO,mBAAmB,IAAI,IAAI,IAClC,OAAO,cACP,OAAO,YACL,mBAAmB,IAAI,IAAI"}

package/dist/introspect/filtering.mjs

@@ -0,0 +1,98 @@
+import "../pagination.mjs";
+import { ColumnNotFound, UnsupportedFilterOperator } from "./errors.mjs";
+import "./types.mjs";
+//#region src/introspect/filtering.ts
+const NULLS = ["is_null", "is_not_null"];
+const EQUALITY = [
+	"eq",
+	"neq",
+	...NULLS
+];
+const ORDERED = [
+	...EQUALITY,
+	"gt",
+	"gte",
+	"lt",
+	"lte"
+];
+const MEMBERSHIP = ["in", "nin"];
+/** Which operators make sense for each column type. */
+const OPERATORS = {
+	string: [
+		...EQUALITY,
+		"like",
+		"ilike",
+		...MEMBERSHIP
+	],
+	number: [...ORDERED, ...MEMBERSHIP],
+	boolean: EQUALITY,
+	date: ORDERED,
+	datetime: ORDERED,
+	uuid: [...EQUALITY, ...MEMBERSHIP],
+	json: NULLS,
+	binary: NULLS,
+	unknown: EQUALITY
+};
+/**
+* Whether a filter's operator applies to the column it names.
+*/
+function validateFilter(filter, column) {
+	if (OPERATORS[column.type].includes(filter.operator)) return { valid: true };
+	return {
+		valid: false,
+		error: new UnsupportedFilterOperator(filter.operator, column.name, column.type)
+	};
+}
+/**
+* Adds each filter to the query as a `where`, after checking the column exists
+* and the operator applies to it.
+*
+* @throws {ColumnNotFound} a filter names a column the table does not have
+* @throws {UnsupportedFilterOperator} an operator does not apply to its column
+*/
+function applyFilters(query, filters, table) {
+	let result = query;
+	for (const filter of filters) {
+		const column = table.columns.find((c) => c.name === filter.column);
+		if (!column) throw new ColumnNotFound(filter.column, table.name);
+		const validation = validateFilter(filter, column);
+		if (!validation.valid) throw validation.error;
+		result = applyFilterCondition(result, filter);
+	}
+	return result;
+}
+function applyFilterCondition(query, filter) {
+	const column = filter.column;
+	const { value } = filter;
+	switch (filter.operator) {
+		case "eq": return query.where(column, "=", value);
+		case "neq": return query.where(column, "!=", value);
+		case "gt": return query.where(column, ">", value);
+		case "gte": return query.where(column, ">=", value);
+		case "lt": return query.where(column, "<", value);
+		case "lte": return query.where(column, "<=", value);
+		case "like": return query.where(column, "like", value);
+		case "ilike": return query.where(column, "ilike", value);
+		case "in": return query.where(column, "in", value);
+		case "nin": return query.where(column, "not in", value);
+		case "is_null": return query.where(column, "is", null);
+		case "is_not_null": return query.where(column, "is not", null);
+	}
+}
+/**
+* Adds an `order by` per sort, in the order given.
+*
+* @throws {ColumnNotFound} a sort names a column the table does not have
+*/
+function applySorting(query, sorts, table) {
+	let result = query;
+	for (const sort of sorts) {
+		if (!table.columns.some((c) => c.name === sort.column)) throw new ColumnNotFound(sort.column, table.name);
+		result = result.orderBy(sort.column, sort.direction === "asc" ? "asc" : "desc");
+	}
+	return result;
+}
+//#endregion
+export { applyFilters, applySorting, validateFilter };
+
+//# sourceMappingURL=filtering.mjs.map

package/dist/introspect/filtering.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"filtering.mjs","names":[],"sources":["../../src/introspect/filtering.ts"],"sourcesContent":["import type { SelectQueryBuilder } from 'kysely';\nimport { Direction } from '../pagination';\nimport { ColumnNotFound, UnsupportedFilterOperator } from './errors';\nimport {\n\ttype ColumnInfo,\n\ttype ColumnType,\n\ttype FilterCondition,\n\tFilterOperator,\n\ttype SortConfig,\n\ttype TableInfo,\n} from './types';\n\nconst NULLS = [FilterOperator.IsNull, FilterOperator.IsNotNull];\nconst EQUALITY = [FilterOperator.Eq, FilterOperator.Neq, ...NULLS];\nconst ORDERED = [\n\t...EQUALITY,\n\tFilterOperator.Gt,\n\tFilterOperator.Gte,\n\tFilterOperator.Lt,\n\tFilterOperator.Lte,\n];\nconst MEMBERSHIP = [FilterOperator.In, FilterOperator.Nin];\n\n/** Which operators make sense for each column type. */\nconst OPERATORS: Record<ColumnType, FilterOperator[]> = {\n\tstring: [\n\t\t...EQUALITY,\n\t\tFilterOperator.Like,\n\t\tFilterOperator.Ilike,\n\t\t...MEMBERSHIP,\n\t],\n\tnumber: [...ORDERED, ...MEMBERSHIP],\n\tboolean: EQUALITY,\n\tdate: ORDERED,\n\tdatetime: ORDERED,\n\tuuid: [...EQUALITY, ...MEMBERSHIP],\n\tjson: NULLS,\n\tbinary: NULLS,\n\tunknown: EQUALITY,\n};\n\n/**\n * Whether a filter's operator applies to the column it names.\n */\nexport function validateFilter(\n\tfilter: FilterCondition,\n\tcolumn: ColumnInfo,\n): { valid: true } | { valid: false; error: UnsupportedFilterOperator } {\n\tif (OPERATORS[column.type].includes(filter.operator)) {\n\t\treturn { valid: true };\n\t}\n\n\treturn {\n\t\tvalid: false,\n\t\terror: new UnsupportedFilterOperator(\n\t\t\tfilter.operator,\n\t\t\tcolumn.name,\n\t\t\tcolumn.type,\n\t\t),\n\t};\n}\n\n/**\n * Adds each filter to the query as a `where`, after checking the column exists\n * and the operator applies to it.\n *\n * @throws {ColumnNotFound} a filter names a column the table does not have\n * @throws {UnsupportedFilterOperator} an operator does not apply to its column\n */\nexport function applyFilters<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tfilters: FilterCondition[],\n\ttable: TableInfo,\n): SelectQueryBuilder<DB, TB, O> {\n\tlet result = query;\n\n\tfor (const filter of filters) {\n\t\tconst column = table.columns.find((c) => c.name === filter.column);\n\t\tif (!column) {\n\t\t\tthrow new ColumnNotFound(filter.column, table.name);\n\t\t}\n\n\t\tconst validation = validateFilter(filter, column);\n\t\tif (!validation.valid) {\n\t\t\tthrow validation.error;\n\t\t}\n\n\t\tresult = applyFilterCondition(result, filter);\n\t}\n\n\treturn result;\n}\n\nfunction applyFilterCondition<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tfilter: FilterCondition,\n): SelectQueryBuilder<DB, TB, O> {\n\t// The column was checked against the introspected table, which the query's\n\t// static types know nothing about.\n\tconst column = filter.column as any;\n\tconst { value } = filter;\n\n\tswitch (filter.operator) {\n\t\tcase FilterOperator.Eq:\n\t\t\treturn query.where(column, '=', value);\n\t\tcase FilterOperator.Neq:\n\t\t\treturn query.where(column, '!=', value);\n\t\tcase FilterOperator.Gt:\n\t\t\treturn query.where(column, '>', value);\n\t\tcase FilterOperator.Gte:\n\t\t\treturn query.where(column, '>=', value);\n\t\tcase FilterOperator.Lt:\n\t\t\treturn query.where(column, '<', value);\n\t\tcase FilterOperator.Lte:\n\t\t\treturn query.where(column, '<=', value);\n\t\tcase FilterOperator.Like:\n\t\t\treturn query.where(column, 'like', value);\n\t\tcase FilterOperator.Ilike:\n\t\t\treturn query.where(column, 'ilike', value);\n\t\tcase FilterOperator.In:\n\t\t\treturn query.where(column, 'in', value as unknown[]);\n\t\tcase FilterOperator.Nin:\n\t\t\treturn query.where(column, 'not in', value as unknown[]);\n\t\tcase FilterOperator.IsNull:\n\t\t\treturn query.where(column, 'is', null);\n\t\tcase FilterOperator.IsNotNull:\n\t\t\treturn query.where(column, 'is not', null);\n\t}\n}\n\n/**\n * Adds an `order by` per sort, in the order given.\n *\n * @throws {ColumnNotFound} a sort names a column the table does not have\n */\nexport function applySorting<DB, TB extends keyof DB, O>(\n\tquery: SelectQueryBuilder<DB, TB, O>,\n\tsorts: SortConfig[],\n\ttable: TableInfo,\n): SelectQueryBuilder<DB, TB, O> {\n\tlet result = query;\n\n\tfor (const sort of sorts) {\n\t\tif (!table.columns.some((c) => c.name === sort.column)) {\n\t\t\tthrow new ColumnNotFound(sort.column, table.name);\n\t\t}\n\n\t\tresult = result.orderBy(\n\t\t\tsort.column as any,\n\t\t\tsort.direction === Direction.Asc ? 'asc' : 'desc',\n\t\t);\n\t}\n\n\treturn result;\n}\n"],"mappings":";;;;AAYA,MAAM,QAAQ,CAAA,WAAA,aAAgD;AAC9D,MAAM,WAAW;;;CAAwC,GAAG;AAAK;AACjE,MAAM,UAAU;CACf,GAAG;;;;;AAKJ;AACA,MAAM,aAAa,CAAA,MAAA,KAAsC;;AAGzD,MAAM,YAAkD;CACvD,QAAQ;EACP,GAAG;;;EAGH,GAAG;CACJ;CACA,QAAQ,CAAC,GAAG,SAAS,GAAG,UAAU;CAClC,SAAS;CACT,MAAM;CACN,UAAU;CACV,MAAM,CAAC,GAAG,UAAU,GAAG,UAAU;CACjC,MAAM;CACN,QAAQ;CACR,SAAS;AACV;;;;AAKA,SAAgB,eACf,QACA,QACuE;CACvE,IAAI,UAAU,OAAO,KAAK,CAAC,SAAS,OAAO,QAAQ,GAClD,OAAO,EAAE,OAAO,KAAK;CAGtB,OAAO;EACN,OAAO;EACP,OAAO,IAAI,0BACV,OAAO,UACP,OAAO,MACP,OAAO,IACR;CACD;AACD;;;;;;;;AASA,SAAgB,aACf,OACA,SACA,OACgC;CAChC,IAAI,SAAS;CAEb,KAAK,MAAM,UAAU,SAAS;EAC7B,MAAM,SAAS,MAAM,QAAQ,MAAM,MAAM,EAAE,SAAS,OAAO,MAAM;EACjE,IAAI,CAAC,QACJ,MAAM,IAAI,eAAe,OAAO,QAAQ,MAAM,IAAI;EAGnD,MAAM,aAAa,eAAe,QAAQ,MAAM;EAChD,IAAI,CAAC,WAAW,OACf,MAAM,WAAW;EAGlB,SAAS,qBAAqB,QAAQ,MAAM;CAC7C;CAEA,OAAO;AACR;AAEA,SAAS,qBACR,OACA,QACgC;CAGhC,MAAM,SAAS,OAAO;CACtB,MAAM,EAAE,UAAU;CAElB,QAAQ,OAAO,UAAf;EACC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,KAAK,KAAK;EACtC,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAK;EACvC,KAAA,QACC,OAAO,MAAM,MAAM,QAAQ,QAAQ,KAAK;EACzC,KAAA,SACC,OAAO,MAAM,MAAM,QAAQ,SAAS,KAAK;EAC1C,KAAA,MACC,OAAO,MAAM,MAAM,QAAQ,MAAM,KAAkB;EACpD,KAAA,OACC,OAAO,MAAM,MAAM,QAAQ,UAAU,KAAkB;EACxD,KAAA,WACC,OAAO,MAAM,MAAM,QAAQ,MAAM,IAAI;EACtC,KAAA,eACC,OAAO,MAAM,MAAM,QAAQ,UAAU,IAAI;CAC3C;AACD;;;;;;AAOA,SAAgB,aACf,OACA,OACA,OACgC;CAChC,IAAI,SAAS;CAEb,KAAK,MAAM,QAAQ,OAAO;EACzB,IAAI,CAAC,MAAM,QAAQ,MAAM,MAAM,EAAE,SAAS,KAAK,MAAM,GACpD,MAAM,IAAI,eAAe,KAAK,QAAQ,MAAM,IAAI;EAGjD,SAAS,OAAO,QACf,KAAK,QACL,KAAK,cAAA,QAA8B,QAAQ,MAC5C;CACD;CAEA,OAAO;AACR"}

package/dist/introspect/handler.cjs

@@ -0,0 +1,159 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_pagination = require("../pagination.cjs");
+const require_introspect_errors = require("./errors.cjs");
+const require_introspect_types = require("./types.cjs");
+const require_introspect_DataBrowser = require("./DataBrowser.cjs");
+//#region src/introspect/handler.ts
+const OPERATORS = new Set(Object.values(require_introspect_types.FilterOperator));
+/**
+* A read-only JSON API over a Postgres database's structure and rows.
+*
+* A plain `(Request) => Promise<Response>` rather than a router, so it mounts
+* in anything that speaks web `Request`s — Hono, Bun, Deno, a Node adapter —
+* and `@geekmidas/db` takes on no HTTP framework to provide it.
+*
+* | Route                         | Returns                                         |
+* | ----------------------------- | ----------------------------------------------- |
+* | `GET /schemas`                | `{ schemas, browsable }`                        |
+* | `GET /tables?schema=&refresh=`| `{ tables }` with columns and foreign keys      |
+* | `GET /tables/:name?schema=`   | one table                                       |
+* | `GET /tables/:name/rows`      | a page of rows: `{ rows, hasMore, nextCursor }` |
+*
+* Rows take `pageSize` (≤ 100), `cursor`, `sort=col:asc,col2:desc` and filters
+* as `filter[column][operator]=value` — `in`/`nin` take a comma-separated
+* list, `is_null`/`is_not_null` take no value.
+*
+* It exposes every row of every browsable table to whoever can reach it. Mount
+* it only where that is the developer: `gkm dev` serves it at `/__gkm/db` and
+* nothing in a production build does.
+*
+* @example
+* ```typescript
+* const handler = createIntrospectionHandler({ db, basePath: '/__gkm/db' });
+* app.all('/__gkm/db/*', (c) => handler(c.req.raw));
+* ```
+*/
+function createIntrospectionHandler(options) {
+	const browser = new require_introspect_DataBrowser.DataBrowser(options);
+	const basePath = (options.basePath ?? "").replace(/\/+$/, "");
+	return async (request) => {
+		if (request.method !== "GET") return json({
+			error: "MethodNotAllowed",
+			message: "The database API is read-only; only GET is served."
+		}, 405, { allow: "GET" });
+		const url = new URL(request.url);
+		const path = url.pathname.startsWith(basePath) ? url.pathname.slice(basePath.length) : url.pathname;
+		const segments = path.split("/").filter(Boolean).map(decodeURIComponent);
+		const schema = url.searchParams.get("schema") ?? void 0;
+		try {
+			if (segments.length === 1 && segments[0] === "schemas") return json({
+				schemas: await browser.listSchemas(),
+				browsable: browser.schemas
+			});
+			if (segments.length === 1 && segments[0] === "tables") {
+				const refresh = url.searchParams.get("refresh") === "true";
+				const { tables, updatedAt } = await browser.getSchema(refresh);
+				return json({
+					tables: schema ? tables.filter((t) => t.schema === schema) : tables,
+					updatedAt
+				});
+			}
+			if (segments[0] === "tables" && segments[1] && segments.length === 2) {
+				const table = await browser.getTableInfo(segments[1], schema);
+				if (!table) throw new require_introspect_errors.TableNotFound(segments[1], schema ?? browser.schemas[0] ?? "public");
+				return json(table);
+			}
+			if (segments[0] === "tables" && segments[1] && segments[2] === "rows" && segments.length === 3) {
+				const pageSize = Number.parseInt(url.searchParams.get("pageSize") ?? "", 10);
+				const filters = parseFilters(url.searchParams);
+				const sort = parseSort(url.searchParams.get("sort"));
+				return json(await browser.query({
+					table: segments[1],
+					schema,
+					pageSize: Number.isNaN(pageSize) ? void 0 : pageSize,
+					cursor: url.searchParams.get("cursor") || void 0,
+					filters: filters.length > 0 ? filters : void 0,
+					sort: sort.length > 0 ? sort : void 0
+				}));
+			}
+			return json({
+				error: "NotFound",
+				message: `No database route at '${path || "/"}'. Routes: /schemas, /tables, /tables/:name, /tables/:name/rows.`
+			}, 404);
+		} catch (error) {
+			const status = statusFor(error);
+			if (status === void 0) throw error;
+			return json({
+				error: error.name,
+				message: error.message
+			}, status);
+		}
+	};
+}
+/** The caller's mistakes, answered; anything else is the server's and thrown. */
+function statusFor(error) {
+	if (error instanceof require_introspect_errors.TableNotFound) return 404;
+	if (error instanceof require_introspect_errors.ColumnNotFound || error instanceof require_introspect_errors.UnsupportedFilterOperator || error instanceof require_pagination.InvalidCursor) return 400;
+}
+/**
+* `filter[column][operator]=value`. An unknown operator is ignored rather than
+* rejected, as a misspelt one in a hand-typed URL is easier to see in the
+* results than to debug from an error.
+*/
+function parseFilters(params) {
+	const filters = [];
+	for (const [key, value] of params) {
+		const match = key.match(/^filter\[(\w+)\]\[(\w+)\]$/);
+		const column = match?.[1];
+		const operator = match?.[2];
+		if (!column || !operator || !OPERATORS.has(operator)) continue;
+		const op = operator;
+		if (op === "in" || op === "nin") filters.push({
+			column,
+			operator: op,
+			value: value.split(",")
+		});
+		else if (op === "is_null" || op === "is_not_null") filters.push({
+			column,
+			operator: op
+		});
+		else filters.push({
+			column,
+			operator: op,
+			value: parseScalar(value)
+		});
+	}
+	return filters;
+}
+function parseScalar(value) {
+	if (value === "true") return true;
+	if (value === "false") return false;
+	if (value !== "" && !Number.isNaN(Number(value))) return Number(value);
+	return value;
+}
+/** `sort=name:asc,created_at:desc`; a column with no direction is ascending. */
+function parseSort(param) {
+	if (!param) return [];
+	return param.split(",").flatMap((part) => {
+		const [column, direction] = part.split(":");
+		if (!column) return [];
+		return [{
+			column,
+			direction: direction === "desc" ? "desc" : "asc"
+		}];
+	});
+}
+function json(body, status = 200, headers = {}) {
+	const text = JSON.stringify(body, (_key, value) => typeof value === "bigint" ? value.toString() : value);
+	return new Response(text, {
+		status,
+		headers: {
+			"content-type": "application/json; charset=utf-8",
+			...headers
+		}
+	});
+}
+//#endregion
+exports.createIntrospectionHandler = createIntrospectionHandler;
+
+//# sourceMappingURL=handler.cjs.map