@geekmidas/db 10.0.0-alpha.15 → 10.0.0-alpha.151

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

package/dist/introspect/handler.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.cjs","names":["FilterOperator","DataBrowser","TableNotFound","ColumnNotFound","UnsupportedFilterOperator","InvalidCursor"],"sources":["../../src/introspect/handler.ts"],"sourcesContent":["import { Direction, InvalidCursor } from '../pagination';\nimport { DataBrowser } from './DataBrowser';\nimport {\n\tColumnNotFound,\n\tTableNotFound,\n\tUnsupportedFilterOperator,\n} from './errors';\nimport {\n\ttype DataBrowserOptions,\n\ttype FilterCondition,\n\tFilterOperator,\n\ttype SortConfig,\n} from './types';\n\nexport interface IntrospectionHandlerOptions<DB = unknown>\n\textends DataBrowserOptions<DB> {\n\t/**\n\t * The path the handler is mounted under, e.g. `/__gkm/db`. Stripped from\n\t * each request's path before routing, so the handler can be mounted\n\t * anywhere without a router of its own.\n\t */\n\tbasePath?: string;\n}\n\n/** A fetch-style handler: a web `Request` in, a JSON `Response` out. */\nexport type IntrospectionHandler = (request: Request) => Promise<Response>;\n\nconst OPERATORS = new Set<string>(Object.values(FilterOperator));\n\n/**\n * A read-only JSON API over a Postgres database's structure and rows.\n *\n * A plain `(Request) => Promise<Response>` rather than a router, so it mounts\n * in anything that speaks web `Request`s — Hono, Bun, Deno, a Node adapter —\n * and `@geekmidas/db` takes on no HTTP framework to provide it.\n *\n * | Route                         | Returns                                         |\n * | ----------------------------- | ----------------------------------------------- |\n * | `GET /schemas`                | `{ schemas, browsable }`                        |\n * | `GET /tables?schema=&refresh=`| `{ tables }` with columns and foreign keys      |\n * | `GET /tables/:name?schema=`   | one table                                       |\n * | `GET /tables/:name/rows`      | a page of rows: `{ rows, hasMore, nextCursor }` |\n *\n * Rows take `pageSize` (≤ 100), `cursor`, `sort=col:asc,col2:desc` and filters\n * as `filter[column][operator]=value` — `in`/`nin` take a comma-separated\n * list, `is_null`/`is_not_null` take no value.\n *\n * It exposes every row of every browsable table to whoever can reach it. Mount\n * it only where that is the developer: `gkm dev` serves it at `/__gkm/db` and\n * nothing in a production build does.\n *\n * @example\n * ```typescript\n * const handler = createIntrospectionHandler({ db, basePath: '/__gkm/db' });\n * app.all('/__gkm/db/*', (c) => handler(c.req.raw));\n * ```\n */\nexport function createIntrospectionHandler<DB>(\n\toptions: IntrospectionHandlerOptions<DB>,\n): IntrospectionHandler {\n\tconst browser = new DataBrowser(options);\n\tconst basePath = (options.basePath ?? '').replace(/\\/+$/, '');\n\n\treturn async (request) => {\n\t\tif (request.method !== 'GET') {\n\t\t\treturn json(\n\t\t\t\t{\n\t\t\t\t\terror: 'MethodNotAllowed',\n\t\t\t\t\tmessage: 'The database API is read-only; only GET is served.',\n\t\t\t\t},\n\t\t\t\t405,\n\t\t\t\t{ allow: 'GET' },\n\t\t\t);\n\t\t}\n\n\t\tconst url = new URL(request.url);\n\t\tconst path = url.pathname.startsWith(basePath)\n\t\t\t? url.pathname.slice(basePath.length)\n\t\t\t: url.pathname;\n\t\tconst segments = path.split('/').filter(Boolean).map(decodeURIComponent);\n\t\tconst schema = url.searchParams.get('schema') ?? undefined;\n\n\t\ttry {\n\t\t\tif (segments.length === 1 && segments[0] === 'schemas') {\n\t\t\t\treturn json({\n\t\t\t\t\tschemas: await browser.listSchemas(),\n\t\t\t\t\tbrowsable: browser.schemas,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (segments.length === 1 && segments[0] === 'tables') {\n\t\t\t\tconst refresh = url.searchParams.get('refresh') === 'true';\n\t\t\t\tconst { tables, updatedAt } = await browser.getSchema(refresh);\n\t\t\t\treturn json({\n\t\t\t\t\ttables: schema ? tables.filter((t) => t.schema === schema) : tables,\n\t\t\t\t\tupdatedAt,\n\t\t\t\t});\n\t\t\t}\n\n\t\t\tif (segments[0] === 'tables' && segments[1] && segments.length === 2) {\n\t\t\t\tconst table = await browser.getTableInfo(segments[1], schema);\n\t\t\t\tif (!table) {\n\t\t\t\t\tthrow new TableNotFound(\n\t\t\t\t\t\tsegments[1],\n\t\t\t\t\t\tschema ?? browser.schemas[0] ?? 'public',\n\t\t\t\t\t);\n\t\t\t\t}\n\t\t\t\treturn json(table);\n\t\t\t}\n\n\t\t\tif (\n\t\t\t\tsegments[0] === 'tables' &&\n\t\t\t\tsegments[1] &&\n\t\t\t\tsegments[2] === 'rows' &&\n\t\t\t\tsegments.length === 3\n\t\t\t) {\n\t\t\t\tconst pageSize = Number.parseInt(\n\t\t\t\t\turl.searchParams.get('pageSize') ?? '',\n\t\t\t\t\t10,\n\t\t\t\t);\n\t\t\t\tconst filters = parseFilters(url.searchParams);\n\t\t\t\tconst sort = parseSort(url.searchParams.get('sort'));\n\n\t\t\t\treturn json(\n\t\t\t\t\tawait browser.query({\n\t\t\t\t\t\ttable: segments[1],\n\t\t\t\t\t\tschema,\n\t\t\t\t\t\tpageSize: Number.isNaN(pageSize) ? undefined : pageSize,\n\t\t\t\t\t\tcursor: url.searchParams.get('cursor') || undefined,\n\t\t\t\t\t\tfilters: filters.length > 0 ? filters : undefined,\n\t\t\t\t\t\tsort: sort.length > 0 ? sort : undefined,\n\t\t\t\t\t}),\n\t\t\t\t);\n\t\t\t}\n\n\t\t\treturn json(\n\t\t\t\t{\n\t\t\t\t\terror: 'NotFound',\n\t\t\t\t\tmessage: `No database route at '${path || '/'}'. Routes: /schemas, /tables, /tables/:name, /tables/:name/rows.`,\n\t\t\t\t},\n\t\t\t\t404,\n\t\t\t);\n\t\t} catch (error) {\n\t\t\tconst status = statusFor(error);\n\t\t\tif (status === undefined) throw error;\n\t\t\treturn json(\n\t\t\t\t{ error: (error as Error).name, message: (error as Error).message },\n\t\t\t\tstatus,\n\t\t\t);\n\t\t}\n\t};\n}\n\n/** The caller's mistakes, answered; anything else is the server's and thrown. */\nfunction statusFor(error: unknown): number | undefined {\n\tif (error instanceof TableNotFound) return 404;\n\tif (\n\t\terror instanceof ColumnNotFound ||\n\t\terror instanceof UnsupportedFilterOperator ||\n\t\terror instanceof InvalidCursor\n\t) {\n\t\treturn 400;\n\t}\n\treturn undefined;\n}\n\n/**\n * `filter[column][operator]=value`. An unknown operator is ignored rather than\n * rejected, as a misspelt one in a hand-typed URL is easier to see in the\n * results than to debug from an error.\n */\nfunction parseFilters(params: URLSearchParams): FilterCondition[] {\n\tconst filters: FilterCondition[] = [];\n\n\tfor (const [key, value] of params) {\n\t\tconst match = key.match(/^filter\\[(\\w+)\\]\\[(\\w+)\\]$/);\n\t\tconst column = match?.[1];\n\t\tconst operator = match?.[2];\n\t\tif (!column || !operator || !OPERATORS.has(operator)) continue;\n\n\t\tconst op = operator as FilterOperator;\n\t\tif (op === FilterOperator.In || op === FilterOperator.Nin) {\n\t\t\tfilters.push({ column, operator: op, value: value.split(',') });\n\t\t} else if (\n\t\t\top === FilterOperator.IsNull ||\n\t\t\top === FilterOperator.IsNotNull\n\t\t) {\n\t\t\tfilters.push({ column, operator: op });\n\t\t} else {\n\t\t\tfilters.push({ column, operator: op, value: parseScalar(value) });\n\t\t}\n\t}\n\n\treturn filters;\n}\n\nfunction parseScalar(value: string): unknown {\n\tif (value === 'true') return true;\n\tif (value === 'false') return false;\n\tif (value !== '' && !Number.isNaN(Number(value))) return Number(value);\n\treturn value;\n}\n\n/** `sort=name:asc,created_at:desc`; a column with no direction is ascending. */\nfunction parseSort(param: string | null): SortConfig[] {\n\tif (!param) return [];\n\n\treturn param.split(',').flatMap((part) => {\n\t\tconst [column, direction] = part.split(':');\n\t\tif (!column) return [];\n\t\treturn [\n\t\t\t{\n\t\t\t\tcolumn,\n\t\t\t\tdirection: direction === 'desc' ? Direction.Desc : Direction.Asc,\n\t\t\t},\n\t\t];\n\t});\n}\n\nfunction json(\n\tbody: unknown,\n\tstatus = 200,\n\theaders: Record<string, string> = {},\n): Response {\n\t// A row can hold a bigint when the pg client is configured to parse int8,\n\t// and JSON.stringify throws on one.\n\tconst text = JSON.stringify(body, (_key, value) =>\n\t\ttypeof value === 'bigint' ? value.toString() : value,\n\t);\n\treturn new Response(text, {\n\t\tstatus,\n\t\theaders: { 'content-type': 'application/json; charset=utf-8', ...headers },\n\t});\n}\n"],"mappings":"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"}

package/dist/introspect/handler.d.cts

@@ -0,0 +1,43 @@
+import { DataBrowserOptions } from "./types.cjs";
+//#region src/introspect/handler.d.ts
+export interface IntrospectionHandlerOptions<DB = unknown> extends DataBrowserOptions<DB> {
+  /**
+   * The path the handler is mounted under, e.g. `/__gkm/db`. Stripped from
+   * each request's path before routing, so the handler can be mounted
+   * anywhere without a router of its own.
+   */
+  basePath?: string;
+}
+/** A fetch-style handler: a web `Request` in, a JSON `Response` out. */
+export type IntrospectionHandler = (request: Request) => Promise<Response>;
+/**
+ * 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));
+ * ```
+ */
+export declare function createIntrospectionHandler<DB>(options: IntrospectionHandlerOptions<DB>): IntrospectionHandler;
+//#endregion
+//# sourceMappingURL=handler.d.cts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.cts","names":[],"sources":["../../src/introspect/handler.ts"],"mappings":";;iBAciB,4BAA4B,sBACpC,mBAAmB;;;;;;EAM3B;;;YAIW,wBAAwB,SAAS,YAAY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgCjD,2BAA2B,IAC1C,SAAS,4BAA4B,MACnC"}

package/dist/introspect/handler.d.mts

@@ -0,0 +1,43 @@
+import { DataBrowserOptions } from "./types.mjs";
+//#region src/introspect/handler.d.ts
+export interface IntrospectionHandlerOptions<DB = unknown> extends DataBrowserOptions<DB> {
+  /**
+   * The path the handler is mounted under, e.g. `/__gkm/db`. Stripped from
+   * each request's path before routing, so the handler can be mounted
+   * anywhere without a router of its own.
+   */
+  basePath?: string;
+}
+/** A fetch-style handler: a web `Request` in, a JSON `Response` out. */
+export type IntrospectionHandler = (request: Request) => Promise<Response>;
+/**
+ * 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));
+ * ```
+ */
+export declare function createIntrospectionHandler<DB>(options: IntrospectionHandlerOptions<DB>): IntrospectionHandler;
+//#endregion
+//# sourceMappingURL=handler.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.mts","names":[],"sources":["../../src/introspect/handler.ts"],"mappings":";;iBAciB,4BAA4B,sBACpC,mBAAmB;;;;;;EAM3B;;;YAIW,wBAAwB,SAAS,YAAY,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;wBAgCjD,2BAA2B,IAC1C,SAAS,4BAA4B,MACnC"}