agent-sql 0.2.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Arderne
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -55,17 +55,14 @@ import { db } from "@/db";
 // Only the tables listed will be permitted
 // Joins can only use the FKs defined here
 const schema = defineSchema({
-  user: { id },
-  msg: { userId: { user: "id" } },
+  user: { id: null },
+  msg: { userId: { ft: "user", fc: "id" } },
 });
 
 function makeSqlTool(userId: string) {
   // Create a sanitiser function for this tenant
-  const agentSql = createAgentSql({
-    column: "user.id",
-    value: userId,
-    schema,
-  });
+  // Specify one or more column->value pairs that will be enforced
+  const agentSql = createAgentSql(schema, { "user.id": userId });
 
   return tool({
     description: "Run raw SQL against the DB",
@@ -95,11 +92,7 @@ import * as drizzleSchema from "@/db/schema";
 const schema = defineSchemaFromDrizzle(drizzleSchema);
 
 // The rest as before...
-const agentSql = createAgentSql({
-  column: "user.id",
-  value: userId,
-  schema,
-});
+const agentSql = createAgentSql(schema, { "user.id": userId });
 ```
 
 You can also exclude tables if you don't want agents to see them:

package/dist/index.d.mts

@@ -10,10 +10,9 @@ interface GuardCol {
 type WhereGuard = GuardCol & {
   value: GuardVal;
 };
-declare function addGuards(ast: SelectStatement, guard: WhereGuard, limit?: number): Result<SelectStatement>;
-//#endregion
-//#region src/namespec.d.ts
 type OneOrTwoDots<S extends string> = S extends `${infer A}.${infer B}.${infer C}` ? A extends `${string}.${string}` ? never : B extends `${string}.${string}` ? never : C extends `${string}.${string}` ? never : S : S extends `${infer A}.${infer B}` ? A extends `${string}.${string}` ? never : B extends `${string}.${string}` ? never : S : never;
+type SchemaGuardKeys<T> = { [Table in keyof T & string]: `${Table}.${keyof T[Table] & string}` }[keyof T & string];
+declare function applyGuards(ast: SelectStatement, guards: WhereGuard[], limit?: number): Result<SelectStatement>;
 //#endregion
 //#region src/output.d.ts
 declare function outputSql(ast: SelectStatement): string;
@@ -29,33 +28,13 @@ declare function agentSql<S extends string>(sql: string, column: S & OneOrTwoDot
   schema?: Schema;
   limit?: number;
 }): string;
-declare function createAgentSql<S extends string>(_: {
-  column: S & OneOrTwoDots<S>;
-  value: GuardVal;
-  schema?: Schema;
+declare function createAgentSql<T extends Schema, S extends SchemaGuardKeys<T>>(schema: T, guards: Record<S, GuardVal>, opts: {
   limit?: number;
   throws: false;
 }): (expr: string) => Result<string>;
-declare function createAgentSql<S extends string>(_: {
-  column: S & OneOrTwoDots<S>;
-  value: GuardVal;
-  schema?: Schema;
+declare function createAgentSql<T extends Schema, S extends SchemaGuardKeys<T>>(schema: T, guards: Record<S, GuardVal>, opts?: {
   limit?: number;
   throws?: true;
 }): (expr: string) => string;
-declare function createAgentSql<S extends string>(_: {
-  column: S & OneOrTwoDots<S>;
-  value?: undefined;
-  schema?: Schema;
-  limit?: number;
-  throws: false;
-}): (guardVal: GuardVal) => (expr: string) => Result<string>;
-declare function createAgentSql<S extends string>(_: {
-  column: S & OneOrTwoDots<S>;
-  value?: undefined;
-  schema?: Schema;
-  limit?: number;
-  throws?: true;
-}): (guardVal: GuardVal) => (expr: string) => string;
 //#endregion
-export { agentSql, createAgentSql, defineSchema, outputSql, parseSql, addGuards as sanitiseSql };
+export { agentSql, createAgentSql, defineSchema, outputSql, parseSql, applyGuards as sanitiseSql };

package/dist/index.mjs

@@ -247,54 +247,86 @@ function returnOrThrow(result, throws) {
 //#endregion
 //#region src/guard.ts
 const DEFAULT_LIMIT = 1e4;
-function addGuards(ast, guard, limit = DEFAULT_LIMIT) {
-	const ast2 = addWhereGuard(ast, guard);
+function applyGuards(ast, guards, limit = DEFAULT_LIMIT) {
+	const ast2 = addWhereGuard(ast, guards);
 	if (!ast2.ok) return ast2;
 	return addLimitGuard(ast2.data, limit);
 }
-function addWhereGuard(ast, guard) {
-	const { schema, table, column, value } = guard;
-	const tableRef = {
-		type: "table_ref",
-		schema,
-		name: table
-	};
-	if (!checkIfTableRefExists(ast, tableRef)) return Err(new SanitiseError(`The table '${handleTableRef(tableRef)}' must appear in the FROM or JOIN clauses.`));
-	const newClause = {
-		type: "where_comparison",
-		operator: "=",
-		left: {
-			type: "where_value",
-			kind: "column_ref",
-			ref: {
-				type: "column_ref",
-				schema,
-				table,
-				name: column
-			}
-		},
-		right: typeof value === "string" ? {
-			type: "where_value",
-			kind: "string",
-			value
-		} : {
-			type: "where_value",
-			kind: "integer",
+function resolveGuards(guards) {
+	if (guards.length === 0) return Err(new AgentSqlError("At least one guard must be provided."));
+	const result = [];
+	for (const [column, value] of Object.entries(guards)) {
+		const guardCol = resolveSingleGuardCol(column);
+		if (!guardCol.ok) return guardCol;
+		result.push({
+			...guardCol.data,
 			value
-		}
-	};
+		});
+	}
+	return Ok(result);
+}
+function resolveSingleGuardCol(column) {
+	const [a, b, c] = column.split(".");
+	if (a === void 0 || b === void 0) return Err(new AgentSqlError(`Malformed column string: '${column}'. Pass 'table.column'.`));
+	if (c === void 0) return Ok({
+		table: a,
+		column: b
+	});
+	return Err(new AgentSqlError("Specifying guard as schema.table.name not yet supported"));
+}
+function addWhereGuard(ast, guards) {
+	for (const guard of guards) {
+		const tableRef = {
+			type: "table_ref",
+			schema: guard.schema,
+			name: guard.table
+		};
+		if (!checkIfTableRefExists(ast, tableRef)) return Err(new SanitiseError(`The table '${handleTableRef(tableRef)}' must appear in the FROM or JOIN clauses.`));
+	}
+	const [first, ...rest] = guards.map((guard) => {
+		const { schema, table, column, value } = guard;
+		return {
+			type: "where_comparison",
+			operator: "=",
+			left: {
+				type: "where_value",
+				kind: "column_ref",
+				ref: {
+					type: "column_ref",
+					schema,
+					table,
+					name: column
+				}
+			},
+			right: typeof value === "string" ? {
+				type: "where_value",
+				kind: "string",
+				value
+			} : {
+				type: "where_value",
+				kind: "integer",
+				value
+			}
+		};
+	});
+	if (!first) return Err(new AgentSqlError("No guards were provided"));
+	const combined = rest.reduce((acc, clause) => ({
+		type: "where_and",
+		left: acc,
+		right: clause
+	}), first);
 	return Ok({
 		...ast,
 		where: ast.where ? {
 			type: "where_root",
 			inner: {
 				type: "where_and",
-				left: newClause,
+				left: combined,
 				right: ast.where.inner
 			}
 		} : {
 			type: "where_root",
-			inner: newClause
+			inner: combined
 		}
 	});
 }
@@ -358,21 +390,6 @@ function getJoinTableRef(joinTableName, left, right) {
 	};
 }
 //#endregion
-//#region src/namespec.ts
-function getQualifiedColumnFromString(column) {
-	const [a, b, c] = column.split(".");
-	if (a === void 0 || b === void 0) throw new AgentSqlError(`Malformed column string: '${column}'. Pass 'table.column'.`);
-	if (c === void 0) return Ok({
-		table: a,
-		column: b
-	});
-	return Ok({
-		schema: a,
-		table: b,
-		column: c
-	});
-}
-//#endregion
 //#region src/sql.ohm-bundle.js
 const result = makeRecipe([
 	"grammar",
@@ -6433,60 +6450,37 @@ function parseSql(expr) {
 //#region src/index.ts
 function agentSql(sql, column, value, { schema, limit } = {}) {
 	return privateAgentSql(sql, {
-		column,
-		value,
+		guards: { [column]: value },
 		schema,
 		limit,
 		throws: true
 	});
 }
-function createAgentSql({ column, schema, value, limit, throws = true }) {
-	if (value !== void 0) return (expr) => throws ? privateAgentSql(expr, {
-		column,
-		value,
+function createAgentSql(schema, guards, { limit, throws = true } = {}) {
+	return (expr) => throws ? privateAgentSql(expr, {
+		guards,
 		schema,
 		limit,
 		throws
 	}) : privateAgentSql(expr, {
-		column,
-		value,
+		guards,
 		schema,
 		limit,
 		throws
 	});
-	function factory(guardVal) {
-		return throws ? createAgentSql({
-			column,
-			schema,
-			value: guardVal,
-			limit,
-			throws
-		}) : createAgentSql({
-			column,
-			schema,
-			value: guardVal,
-			limit,
-			throws
-		});
-	}
-	return factory;
 }
-function privateAgentSql(sql, { column, value, schema, limit, throws }) {
-	const guardCol = getQualifiedColumnFromString(column);
-	if (!guardCol.ok) throw guardCol.error;
+function privateAgentSql(sql, { guards: guardsRaw, schema, limit, throws }) {
+	const guards = resolveGuards(guardsRaw);
+	if (!guards.ok) throw guards.error;
 	const ast = parseSql(sql);
 	if (!ast.ok) return returnOrThrow(ast, throws);
 	const ast2 = checkJoins(ast.data, schema);
 	if (!ast2.ok) return returnOrThrow(ast2, throws);
-	const where = {
-		...guardCol.data,
-		value
-	};
-	const san = addGuards(ast2.data, where, limit);
+	const san = applyGuards(ast2.data, guards.data, limit);
 	if (!san.ok) return returnOrThrow(san, throws);
 	const res = outputSql(san.data);
 	if (throws) return res;
 	return Ok(res);
 }
 //#endregion
-export { agentSql, createAgentSql, defineSchema, outputSql, parseSql, addGuards as sanitiseSql };
+export { agentSql, createAgentSql, defineSchema, outputSql, parseSql, applyGuards as sanitiseSql };

package/package.json

@@ -1,7 +1,13 @@
 {
   "name": "agent-sql",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A starter for creating a TypeScript package.",
+  "keywords": [
+    "agent",
+    "ai",
+    "postgres",
+    "sql"
+  ],
   "homepage": "https://github.com/carderne/agent-sql#readme",
   "bugs": {
     "url": "https://github.com/carderne/agent-sql/issues"