sqyrl 0.0.2 → 0.1.2

package/README.md

@@ -15,15 +15,44 @@ npm install sqyrl
 ```ts
 import { sqyrl } from "sqyrl";
 
-const sql = sqyrl(`SELECT id, name FROM public.users WHERE status = 'active' LIMIT 10`, {
-  schema: "public",
+const sql = sqyrl(`SELECT id, name FROM users WHERE status = 'active' LIMIT 10`, {
   table: "users",
-  column: "tenant_id",
+  col: "tenant_id",
   value: "acme",
 });
 
 console.log(sql);
-// SELECT id, name FROM public.users WHERE public.users.tenant_id = 'acme' AND status = 'active' LIMIT 10
+// SELECT id, name
+// FROM users
+// WHERE (users.tenant_id = 'acme'
+// AND status = 'active') LIMIT 10
+```
+
+Or, more usefully:
+
+```ts
+import { makeSqyrl } from "sqyrl";
+import { tool } from "ai";
+import { sql } from "drizzle-orm";
+import { db } from "@/db";
+
+function makeSqlTool(orgId: string) {
+  // Create a sanitiser function for this tenant
+  const sqyrl = makeSqyrl({ table: "org", col: "id", value: orgId });
+
+  return tool({
+    description: "Run raw SQL against the DB",
+    inputSchema: z.object({ query: z.string() }),
+    execute: async ({ query }) => {
+      // The LLM can pass any query it likes, we'll sanitise it if possible
+      // and return helpful error messages if not
+      const sanitised = sqyrl(query);
+      // Now we can throw that straight at the db and be confident it'll only
+      // return data from the specified tenant
+      return db.execute(sql.raw(sanitised));
+    },
+  });
+}
 ```
 
 `sqyrl` parses the SQL, enforces a mandatory equality filter on the given column as the outermost `AND` condition (so it cannot be short-circuited by agent-supplied `OR` clauses), and returns the sanitised SQL string.
@@ -35,12 +64,24 @@ console.log(sql);
 
 ## Development
 
+First install [Vite+](https://viteplus.dev/guide/):
+
+```bash
+curl -fsSL https://vite.plus | bash
+```
+
 Install dependencies:
 
 ```bash
 vp install
 ```
 
+Format, lint, typecheck:
+
+```bash
+vp check --fix
+```
+
 Run the unit tests:
 
 ```bash

package/dist/index.d.mts

@@ -1,44 +1,217 @@
 //#region src/ast.d.ts
 interface SelectStatement {
-  type: "select";
+  readonly type: "select";
+  distinct: Distinct | null;
   columns: Column[];
-  from: TableRef;
-  where: WhereExpr | null;
-  limit: number | null;
+  from: SelectFrom;
+  joins: JoinClause[];
+  where: WhereRoot | null;
+  groupBy: GroupByClause | null;
+  having: HavingClause | null;
+  orderBy: OrderByClause | null;
+  limit: LimitClause | null;
+  offset: OffsetClause | null;
 }
-type WhereExpr = WhereAnd | WhereOr | WhereComparison;
+interface Distinct {
+  readonly type: "distinct";
+}
+interface GroupByClause {
+  readonly type: "group_by";
+  items: WhereValue[];
+}
+interface HavingClause {
+  readonly type: "having";
+  expr: WhereExpr;
+}
+interface OrderByClause {
+  readonly type: "order_by";
+  items: OrderByItem[];
+}
+type SortDirection = "asc" | "desc";
+type NullsOrder = "nulls_first" | "nulls_last";
+interface OrderByItem {
+  readonly type: "order_by_item";
+  expr: WhereValue;
+  direction?: SortDirection;
+  nulls?: NullsOrder;
+}
+interface OffsetClause {
+  readonly type: "offset";
+  value: number;
+}
+type JoinType = "inner" | "inner_outer" | "left" | "left_outer" | "right" | "right_outer" | "full" | "full_outer" | "cross" | "natural";
+type JoinCondition = {
+  readonly type: "join_on";
+  expr: WhereExpr;
+} | {
+  readonly type: "join_using";
+  columns: string[];
+};
+interface JoinClause {
+  readonly type: "join";
+  joinType: JoinType;
+  table: TableRef;
+  condition: JoinCondition | null;
+}
+type SelectFrom = {
+  readonly type: "select_from";
+  table: TableRef;
+};
+type LimitClause = {
+  readonly type: "limit";
+  value: number;
+};
+type WhereRoot = {
+  readonly type: "where_root";
+  inner: WhereExpr;
+};
+type WhereExpr = WhereAnd | WhereOr | WhereNot | WhereComparison | WhereIsNull | WhereIsBool | WhereBetween | WhereIn | WhereLike;
 interface WhereAnd {
-  type: "and";
+  readonly type: "where_and";
   left: WhereExpr;
   right: WhereExpr;
 }
 interface WhereOr {
-  type: "or";
+  readonly type: "where_or";
   left: WhereExpr;
   right: WhereExpr;
 }
-interface WhereComparison {
-  type: "comparison";
-  operator: "=";
-  column: ColumnRefNode;
+type ComparisonOperator = "=" | "<>" | "!=" | "<" | ">" | "<=" | ">=";
+interface WhereNot {
+  readonly type: "where_not";
+  expr: WhereExpr;
+}
+interface WhereIsNull {
+  readonly type: "where_is_null";
+  not: boolean;
+  expr: WhereValue;
+}
+type IsBoolTarget = boolean | "unknown";
+interface WhereIsBool {
+  readonly type: "where_is_bool";
+  not: boolean;
+  expr: WhereValue;
+  target: IsBoolTarget;
+}
+interface WhereBetween {
+  readonly type: "where_between";
+  not: boolean;
+  expr: WhereValue;
+  low: WhereValue;
+  high: WhereValue;
+}
+interface WhereIn {
+  readonly type: "where_in";
+  not: boolean;
+  expr: WhereValue;
+  list: WhereValue[];
+}
+type LikeOp = "like";
+interface WhereLike {
+  readonly type: "where_like";
+  not: boolean;
+  op: LikeOp;
+  expr: WhereValue;
+  pattern: WhereValue;
+}
+type ArithOp = "+" | "-" | "*" | "/" | "%" | "||";
+interface WhereArith {
+  readonly type: "where_arith";
+  op: ArithOp;
+  left: WhereValue;
+  right: WhereValue;
+}
+interface WhereUnaryMinus {
+  readonly type: "where_unary_minus";
+  expr: WhereValue;
+}
+interface CaseWhen {
+  condition: WhereValue;
+  result: WhereValue;
+}
+interface CaseExpr {
+  readonly type: "case_expr";
+  subject: WhereValue | null;
+  whens: CaseWhen[];
+  else: WhereValue | null;
+}
+interface CastExpr {
+  readonly type: "cast_expr";
+  expr: WhereValue;
+  typeName: string;
+}
+type WhereValue = {
+  readonly type: "where_value";
+  kind: "string";
   value: string;
+} | {
+  readonly type: "where_value";
+  kind: "integer";
+  value: number;
+} | {
+  readonly type: "where_value";
+  kind: "float";
+  value: number;
+} | {
+  readonly type: "where_value";
+  kind: "bool";
+  value: boolean;
+} | {
+  readonly type: "where_value";
+  kind: "null";
+} | {
+  readonly type: "where_value";
+  kind: "column_ref";
+  ref: ColumnRef;
+} | {
+  readonly type: "where_value";
+  kind: "func_call";
+  func: FuncCall;
+} | WhereArith | WhereUnaryMinus | CaseExpr | CastExpr;
+interface WhereComparison {
+  readonly type: "where_comparison";
+  operator: ComparisonOperator;
+  left: WhereValue;
+  right: WhereValue;
 }
-interface ColumnRefNode {
-  type: "column_ref";
+interface ColumnRef {
+  readonly type: "column_ref";
+  schema?: string;
   table?: string;
   name: string;
 }
-interface Column {
-  type: "wildcard" | "qualified_wildcard" | "qualified" | "simple";
+type FuncCallArg = {
+  kind: "wildcard";
+} | {
+  kind: "args";
+  distinct: boolean;
+  args: WhereValue[];
+};
+interface FuncCall {
+  readonly type: "func_call";
+  name: string;
+  args: FuncCallArg;
+}
+interface ColumnExpr {
+  readonly type: "column_expr";
+  kind: "wildcard" | "qualified_wildcard" | "expr";
   table?: string;
-  name?: string;
-  alias?: string;
+  expr?: WhereValue;
+}
+interface Column {
+  readonly type: "column";
+  expr: ColumnExpr;
+  alias?: Alias;
+}
+interface Alias {
+  readonly type: "alias";
+  name: string;
 }
 interface TableRef {
-  type: "table";
+  readonly type: "table_ref";
   schema?: string;
   name: string;
-  alias?: string;
+  alias?: Alias;
 }
 //#endregion
 //#region src/output.d.ts
@@ -48,31 +221,21 @@ declare function outputSql(ast: SelectStatement): string;
 declare function parseSql(expr: string): SelectStatement;
 //#endregion
 //#region src/sanitise.d.ts
-declare function sanitiseSql({
-  ast,
+interface WhereGuard {
+  schema?: string;
+  table: string;
+  col: string;
+  value: string | number;
+}
+declare function sanitiseSql(ast: SelectStatement, {
   schema,
   table,
   col,
   value
-}: {
-  ast: SelectStatement;
-  schema: string;
-  table: string;
-  col: string;
-  value: string;
-}): SelectStatement;
+}: WhereGuard): SelectStatement;
 //#endregion
 //#region src/index.d.ts
-declare function sqyrl(expr: string, {
-  schema,
-  table,
-  column,
-  value
-}: {
-  schema: string;
-  table: string;
-  column: string;
-  value: string;
-}): string;
+declare function sqyrl(expr: string, whereGuard: WhereGuard): string;
+declare function makeSqyrl(whereGuard: WhereGuard): (expr: string) => string;
 //#endregion
-export { outputSql, parseSql, sanitiseSql, sqyrl };
+export { makeSqyrl, outputSql, parseSql, sanitiseSql, sqyrl };