feat: add schema.nullable for optional values

Accepts null and undefined in addition to the inner descriptor's
accepted values, and emits the bare SQL NULL literal when nullish.
Non-null values delegate to the inner descriptor's validate and
escape. The existing null-rejection path for non-nullable descriptors
is preserved with its dedicated error message.

Author: bug3

README.md

@@ -112,6 +112,7 @@ const { sql } = getEvents({
 | `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)` |
+| `schema.nullable(inner)` | `null` / `undefined` or `inner` value | `schema.nullable(schema.isoTimestamp)` |
 
 ### Array Values (IN clauses)
 
@@ -132,6 +133,26 @@ const { sql } = getByIds({ table: 'users', ids: [1, 2, 3] });
 // ... WHERE id IN (1, 2, 3)
 ```
 
+### Nullable Values
+
+`schema.nullable(inner)` accepts `null` / `undefined` in addition to whatever `inner` accepts, and emits the bare SQL `NULL` literal. Do not wrap the placeholder in quotes in your template, since `NULL` must be unquoted.
+
+```sql
+-- queries/updateLogin.sql
+UPDATE {{table}} SET last_login = {{lastLogin}} WHERE id = {{id}}
+```
+
+```typescript
+const updateLogin = defineQuery('./queries/updateLogin.sql', {
+  table: schema.identifier,
+  lastLogin: schema.nullable(schema.isoTimestamp),
+  id: schema.positiveInt,
+});
+
+updateLogin({ table: 'users', lastLogin: null, id: 1 });
+// ... SET last_login = NULL ...
+```
+
 ### Custom Schema Types
 
 Define your own type descriptors for project-specific validation:

llms.txt

@@ -60,6 +60,7 @@ Schema mode validates at define-time (schema keys must match template tokens) an
 - `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
+- `schema.nullable(inner)` - accepts null/undefined (emits SQL `NULL`) or delegates to `inner`; template must not quote the placeholder
 
 ### Custom schema types
 

src/index.ts

@@ -73,11 +73,11 @@ export function defineQuery(
             const value = params[key];
 
             if (schemaDef) {
-                if (value === null || value === undefined) {
-                    throw new Error(`Validation failed for '${key}': value cannot be null or undefined`);
-                }
                 const desc = schemaDef[key];
                 if (!desc.validate(value)) {
+                    if (value === null || value === undefined) {
+                        throw new Error(`Validation failed for '${key}': value cannot be null or undefined`);
+                    }
                     throw new Error(
                         `Schema validation failed for '${key}': received ${typeof value} (${JSON.stringify(value)})`,
                     );

src/schema.ts

@@ -1,4 +1,4 @@
-import { SQL_INJECTION_PATTERNS } from './validator';
+import { SQL_INJECTION_PATTERNS, escapeValue } from './validator';
 
 const ISO_DATE_REGEX = /^\d{4}-\d{2}-\d{2}$/;
 const ISO_TIMESTAMP_REGEX = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$/;
@@ -76,6 +76,14 @@ export const schema = {
             .map((v) => (inner.escape ? inner.escape(v) : formatArrayElement(v)))
             .join(', '),
     }),
+
+    nullable: <T>(inner: TypeDescriptor<T>): TypeDescriptor<T | null> => ({
+        validate: (val) => val === null || val === undefined || inner.validate(val),
+        escape: (val) => {
+            if (val === null || val === undefined) return 'NULL';
+            return inner.escape ? inner.escape(val) : escapeValue(val);
+        },
+    }),
 };
 
 export type SchemaDefinition = Record<string, TypeDescriptor>;

tests/define-query.test.ts

@@ -329,6 +329,65 @@ describe('defineQuery — schema mode', () => {
         });
     });
 
+    describe('schema.nullable', () => {
+        it('renders null as the SQL NULL literal', () => {
+            const query = defineQuery(fixture('nullable.sql'), {
+                table: schema.identifier,
+                lastLogin: schema.nullable(schema.isoTimestamp),
+                id: schema.positiveInt,
+            });
+            const { sql } = query({ table: 'users', lastLogin: null, id: 1 });
+            expect(sql).toContain('last_login = NULL');
+        });
+
+        it('renders undefined as the SQL NULL literal', () => {
+            const query = defineQuery(fixture('nullable.sql'), {
+                table: schema.identifier,
+                lastLogin: schema.nullable(schema.isoTimestamp),
+                id: schema.positiveInt,
+            });
+            const { sql } = query({
+                table: 'users',
+                lastLogin: undefined as unknown as string,
+                id: 1,
+            });
+            expect(sql).toContain('last_login = NULL');
+        });
+
+        it('delegates to the inner escape for non-null values', () => {
+            const query = defineQuery(fixture('nullable.sql'), {
+                table: schema.identifier,
+                lastLogin: schema.nullable(schema.isoTimestamp),
+                id: schema.positiveInt,
+            });
+            const { sql } = query({
+                table: 'users',
+                lastLogin: '2022-02-22T22:02:22Z',
+                id: 1,
+            });
+            expect(sql).toContain('last_login = 2022-02-22T22:02:22Z');
+        });
+
+        it('still rejects invalid non-null values', () => {
+            const query = defineQuery(fixture('nullable.sql'), {
+                table: schema.identifier,
+                lastLogin: schema.nullable(schema.isoTimestamp),
+                id: schema.positiveInt,
+            });
+            expect(() => query({ table: 'users', lastLogin: 'nope', id: 1 }))
+                .toThrow('Schema validation failed');
+        });
+
+        it('non-nullable descriptors still reject null with the dedicated message', () => {
+            const query = defineQuery(fixture('simple.sql'), {
+                table: schema.identifier,
+                id: schema.positiveInt,
+            });
+            const params = { table: 'users', id: null } as unknown as { table: string; id: number };
+            expect(() => query(params)).toThrow('cannot be null or undefined');
+        });
+    });
+
     describe('custom schema types', () => {
         it('accepts a custom type descriptor', () => {
             const prodTable = {

tests/fixtures/nullable.sql

@@ -0,0 +1,5 @@
+UPDATE {{table}}
+SET
+  last_login = {{lastLogin}}
+WHERE
+  id = {{id}}

tests/schema.test.ts

@@ -231,6 +231,38 @@ describe('schema.array', () => {
     });
 });
 
+describe('schema.nullable', () => {
+    it('accepts null and undefined', () => {
+        const nstr = schema.nullable(schema.string);
+        expect(nstr.validate(null)).toBe(true);
+        expect(nstr.validate(undefined)).toBe(true);
+    });
+
+    it('delegates validation to the inner descriptor for non-null values', () => {
+        const nstr = schema.nullable(schema.string);
+        expect(nstr.validate('hello')).toBe(true);
+        expect(nstr.validate('x; DROP TABLE y')).toBe(false);
+
+        const nint = schema.nullable(schema.positiveInt);
+        expect(nint.validate(5)).toBe(true);
+        expect(nint.validate(-1)).toBe(false);
+    });
+
+    it('renders null and undefined as the SQL NULL literal', () => {
+        const nstr = schema.nullable(schema.string);
+        expect(nstr.escape?.(null)).toBe('NULL');
+        expect(nstr.escape?.(undefined)).toBe('NULL');
+    });
+
+    it('delegates escape to the inner descriptor for non-null values', () => {
+        const nstr = schema.nullable(schema.string);
+        expect(nstr.escape?.("O'Brien")).toBe("O''Brien");
+
+        const nint = schema.nullable(schema.positiveInt);
+        expect(nint.escape?.(42)).toBe('42');
+    });
+});
+
 describe('schema.s3Path', () => {
     it('accepts valid S3 paths', () => {
         expect(schema.s3Path.validate('s3://my-bucket/data/')).toBe(true);