feat: add schema.array for IN clause values

Validates every element against an inner descriptor and renders a
comma-separated SQL list. Strings are quoted with single quotes
escaped, numbers and booleans are rendered raw. Empty arrays are
rejected. Closes a gap where users previously had to manually join
array values, which bypassed the injection denylist.

TypeDescriptor now has an optional escape(val) method; when set, the
renderer uses it instead of the default escapeValue to format the
interpolated string.

Author: bug3

README.md

@@ -111,6 +111,26 @@ const { sql } = getEvents({
 | `schema.positiveInt` | Positive integer | `100` |
 | `schema.enum(...)` | Whitelist of allowed values | `schema.enum('asc', 'desc')` |
 | `schema.s3Path` | S3 URI | `'s3://athena-results/queries/'` |
+| `schema.array(inner)` | Non-empty array of `inner` values | `schema.array(schema.positiveInt)` |
+
+### Array Values (IN clauses)
+
+`schema.array(inner)` validates every element against `inner` and renders a comma-separated SQL list. Strings are quoted and their single quotes escaped; numbers and booleans are rendered raw. Empty arrays are rejected.
+
+```sql
+-- queries/getByIds.sql
+SELECT * FROM {{table}} WHERE id IN ({{ids}})
+```
+
+```typescript
+const getByIds = defineQuery('./queries/getByIds.sql', {
+  table: schema.identifier,
+  ids: schema.array(schema.positiveInt),
+});
+
+const { sql } = getByIds({ table: 'users', ids: [1, 2, 3] });
+// ... WHERE id IN (1, 2, 3)
+```
 
 ### Custom Schema Types
 

llms.txt

@@ -59,6 +59,7 @@ Schema mode validates at define-time (schema keys must match template tokens) an
 - `schema.positiveInt` - integer greater than 0
 - `schema.enum(...values)` - whitelist of allowed string values
 - `schema.s3Path` - S3 URI (s3://athena-results/queries/)
+- `schema.array(inner)` - non-empty array; renders `'a', 'b'` for strings, `1, 2, 3` for numbers; rejects empty arrays
 
 ### Custom schema types
 

src/index.ts

@@ -82,7 +82,7 @@ export function defineQuery(
                         `Schema validation failed for '${key}': received ${typeof value} (${JSON.stringify(value)})`,
                     );
                 }
-                values[key] = escapeValue(value);
+                values[key] = desc.escape ? desc.escape(value) : escapeValue(value);
             } else {
                 values[key] = validateAndConvert(key, value);
             }

src/schema.ts

@@ -9,12 +9,18 @@ const S3_PATH_REGEX = /^s3:\/\/(?![^/]*\.\.)[a-z0-9][a-z0-9.-]{1,61}[a-z0-9](\/[
 export interface TypeDescriptor<T = unknown> {
     readonly __phantom?: T;
     validate(val: unknown): boolean;
+    escape?(val: unknown): string;
 }
 
 function descriptor<T>(validate: (val: unknown) => boolean): TypeDescriptor<T> {
     return { validate };
 }
 
+function formatArrayElement(val: unknown): string {
+    if (typeof val === 'string') return `'${val.replace(/'/g, "''")}'`;
+    return String(val);
+}
+
 function isString(val: unknown): val is string {
     return typeof val === 'string';
 }
@@ -61,6 +67,15 @@ export const schema = {
     enum: <T extends string>(...values: T[]): TypeDescriptor<T> => descriptor<T>(
         (val) => isString(val) && (values as string[]).includes(val),
     ),
+
+    array: <T>(inner: TypeDescriptor<T>): TypeDescriptor<T[]> => ({
+        validate: (val) => Array.isArray(val)
+            && val.length > 0
+            && val.every((v) => inner.validate(v)),
+        escape: (val) => (val as unknown[])
+            .map((v) => (inner.escape ? inner.escape(v) : formatArrayElement(v)))
+            .join(', '),
+    }),
 };
 
 export type SchemaDefinition = Record<string, TypeDescriptor>;

tests/define-query.test.ts

@@ -290,6 +290,45 @@ describe('defineQuery — schema mode', () => {
         });
     });
 
+    describe('schema.array', () => {
+        it('renders a list of numbers without quotes', () => {
+            const query = defineQuery(fixture('in-clause.sql'), {
+                table: schema.identifier,
+                ids: schema.array(schema.positiveInt),
+            });
+            const { sql } = query({ table: 'users', ids: [1, 2, 3] });
+            expect(sql).toContain('IN (1, 2, 3)');
+        });
+
+        it('renders a list of strings with quotes and escapes single quotes', () => {
+            const query = defineQuery(fixture('in-clause.sql'), {
+                table: schema.identifier,
+                ids: schema.array(schema.string),
+            });
+            const { sql } = query({ table: 'users', ids: ['a', "O'Brien"] });
+            expect(sql).toContain("IN ('a', 'O''Brien')");
+        });
+
+        it('rejects an empty array', () => {
+            const query = defineQuery(fixture('in-clause.sql'), {
+                table: schema.identifier,
+                ids: schema.array(schema.positiveInt),
+            });
+            expect(() => query({ table: 'users', ids: [] })).toThrow('Schema validation failed');
+        });
+
+        it('rejects a mixed-type array when inner is strict', () => {
+            const query = defineQuery(fixture('in-clause.sql'), {
+                table: schema.identifier,
+                ids: schema.array(schema.positiveInt),
+            });
+            expect(() => query({
+                table: 'users',
+                ids: [1, -1, 2] as unknown as number[],
+            })).toThrow('Schema validation failed');
+        });
+    });
+
     describe('custom schema types', () => {
         it('accepts a custom type descriptor', () => {
             const prodTable = {

tests/fixtures/in-clause.sql

@@ -0,0 +1,6 @@
+SELECT
+  *
+FROM
+  {{table}}
+WHERE
+  id IN ({{ids}})

tests/schema.test.ts

@@ -189,6 +189,48 @@ describe('schema.enum', () => {
     });
 });
 
+describe('schema.array', () => {
+    it('accepts non-empty arrays whose elements pass the inner validator', () => {
+        const ints = schema.array(schema.positiveInt);
+        expect(ints.validate([1, 2, 3])).toBe(true);
+
+        const dates = schema.array(schema.isoDate);
+        expect(dates.validate(['2022-01-01', '2022-02-02'])).toBe(true);
+
+        const statuses = schema.array(schema.enum('active', 'pending'));
+        expect(statuses.validate(['active', 'pending'])).toBe(true);
+    });
+
+    it('rejects empty arrays', () => {
+        expect(schema.array(schema.positiveInt).validate([])).toBe(false);
+    });
+
+    it('rejects non-arrays', () => {
+        expect(schema.array(schema.positiveInt).validate(1)).toBe(false);
+        expect(schema.array(schema.positiveInt).validate('1,2,3')).toBe(false);
+        expect(schema.array(schema.positiveInt).validate(null)).toBe(false);
+    });
+
+    it('rejects arrays with any invalid element', () => {
+        expect(schema.array(schema.positiveInt).validate([1, -1, 2])).toBe(false);
+        expect(schema.array(schema.isoDate).validate(['2022-01-01', 'bad'])).toBe(false);
+    });
+
+    it('rejects arrays of strings with SQL injection', () => {
+        expect(schema.array(schema.string).validate(['a', "b'; DROP TABLE x"])).toBe(false);
+    });
+
+    it('escapes strings by quoting and doubling single quotes', () => {
+        const arr = schema.array(schema.string);
+        expect(arr.escape?.(['a', "O'Brien"])).toBe("'a', 'O''Brien'");
+    });
+
+    it('escapes numbers without quotes', () => {
+        const arr = schema.array(schema.positiveInt);
+        expect(arr.escape?.([1, 2, 3])).toBe('1, 2, 3');
+    });
+});
+
 describe('schema.s3Path', () => {
     it('accepts valid S3 paths', () => {
         expect(schema.s3Path.validate('s3://my-bucket/data/')).toBe(true);