feat: 🎸 add function type to schema

Author: mjancarik

README.md

@@ -426,6 +426,7 @@ const schema = s.object({
 - `s.number()` - Number validation
 - `s.boolean()` - Boolean validation
 - `s.date()` - Date validation
+- `s.function()` - Function validation
 - `s.object(def)` - Object validation
 - `s.array(def)` - Array validation
 - `s.literal(value)` - Literal value validation
@@ -590,6 +591,27 @@ const dateSchemaFunc = s.date({
 });
 ```
 
+#### `s.function(options?)`
+
+Creates a function schema that validates the value is callable.
+
+- **`message`**: Can be either a constant string or a function `(value) => string`.
+
+```typescript
+const callbackSchema = s.function();
+callbackSchema.parse(() => {});        // () => {}
+callbackSchema.parse(async () => {});  // async () => {}
+callbackSchema.parse('hello');         // throws
+
+const callbackSchemaMsg = s.function({
+  message: 'Expected a callback function.',
+});
+
+const callbackSchemaFunc = s.function({
+  message: (value) => `Custom error: "${value}" is not a function.`,
+});
+```
+
 #### `s.object(definition, options?)`
 
 Creates an object schema with the given definition. You can optionally pass `options` to customize error messages.

src/__tests__/function-edge-cases.test.mjs

@@ -0,0 +1,120 @@
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { s } from '../index.ts';
+
+describe('s.function()', () => {
+  // ─── valid inputs ──────────────────────────────────────────────────────────
+  it('passes an arrow function', () => {
+    const fn = () => {};
+    assert.strictEqual(s.function().parse(fn), fn);
+  });
+
+  it('passes a named function', () => {
+    function handler() {}
+    assert.strictEqual(s.function().parse(handler), handler);
+  });
+
+  it('passes an async function', () => {
+    const fn = async () => {};
+    assert.strictEqual(s.function().parse(fn), fn);
+  });
+
+  it('passes a function with arguments', () => {
+    const fn = (a, b) => a + b;
+    assert.strictEqual(s.function().parse(fn), fn);
+  });
+
+  it('passes a class constructor (callable)', () => {
+    class MyClass {}
+    assert.strictEqual(s.function().parse(MyClass), MyClass);
+  });
+
+  // ─── invalid inputs ────────────────────────────────────────────────────────
+  it('throws for a string', () =>
+    assert.throws(() => s.function().parse('hello')));
+
+  it('throws for a number', () => assert.throws(() => s.function().parse(42)));
+
+  it('throws for null', () => assert.throws(() => s.function().parse(null)));
+
+  it('throws for undefined', () =>
+    assert.throws(() => s.function().parse(undefined)));
+
+  it('throws for a plain object', () =>
+    assert.throws(() => s.function().parse({ call: () => {} })));
+
+  it('throws for an array', () => assert.throws(() => s.function().parse([])));
+
+  it('throws for a boolean', () =>
+    assert.throws(() => s.function().parse(true)));
+
+  // ─── error message ─────────────────────────────────────────────────────────
+  it('default error message contains the invalid value', () => {
+    const result = s.function().safeParse('nope');
+    assert.equal(result.success, false);
+    assert.ok(result.error.message.includes('nope'));
+  });
+
+  it('supports custom message as string', () => {
+    const schema = s.function({ message: 'Expected a callback' });
+    const result = schema.safeParse(42);
+    assert.equal(result.success, false);
+    assert.equal(result.error.message, 'Expected a callback');
+  });
+
+  it('supports custom message as function', () => {
+    const schema = s.function({ message: (v) => `"${v}" is not a function` });
+    const result = schema.safeParse(42);
+    assert.equal(result.success, false);
+    assert.equal(result.error.message, '"42" is not a function');
+  });
+
+  // ─── modifiers ─────────────────────────────────────────────────────────────
+  it('.optional() allows undefined', () => {
+    const schema = s.function().optional();
+    assert.equal(schema.parse(undefined), undefined);
+    const fn = () => {};
+    assert.strictEqual(schema.parse(fn), fn);
+  });
+
+  it('.nullable() allows null', () => {
+    const schema = s.function().nullable();
+    assert.equal(schema.parse(null), null);
+    const fn = () => {};
+    assert.strictEqual(schema.parse(fn), fn);
+  });
+
+  it('.refine() chains correctly', () => {
+    const schema = s.function().refine((fn) => fn.length === 2, {
+      message: 'Must accept exactly 2 arguments',
+    });
+    assert.ok(schema.parse((a, b) => a + b));
+    assert.throws(() => schema.parse(() => {}));
+  });
+
+  // ─── inside s.object() ─────────────────────────────────────────────────────
+  it('works as a field inside s.object()', () => {
+    const schema = s.object({
+      name: s.string(),
+      onClick: s.function(),
+    });
+    const fn = () => {};
+    const result = schema.parse({ name: 'btn', onClick: fn });
+    assert.equal(result.name, 'btn');
+    assert.strictEqual(result.onClick, fn);
+  });
+
+  it('fails inside s.object() when field is not a function', () => {
+    const schema = s.object({
+      name: s.string(),
+      onClick: s.function(),
+    });
+    assert.throws(() => schema.parse({ name: 'btn', onClick: 'not-a-fn' }));
+  });
+
+  it('safeParse returns success:false for invalid function field', () => {
+    const schema = s.object({ handler: s.function() });
+    const result = schema.safeParse({ handler: null });
+    assert.equal(result.success, false);
+  });
+});

src/index.ts

@@ -80,6 +80,9 @@ export interface NumberSchemaInterface
 export interface BooleanSchemaInterface
   extends SchemaInterface<boolean, boolean> {}
 export interface DateSchemaInterface extends SchemaInterface<Date, Date> {}
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+export interface FunctionSchemaInterface
+  extends SchemaInterface<Function, Function> {}
 export interface ArraySchemaInterface<T extends SchemaType>
   extends SchemaInterface<
     Array<ReturnType<T['parse']>>,
@@ -121,6 +124,8 @@ export type SchemaType =
   | SchemaInterface<Date, Date | undefined>
   | SchemaInterface<Date, Date | null>
   | SchemaInterface<Date, Date | undefined | null>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  | FunctionSchemaInterface
   | EnumSchemaInterface<string>
   | UnionSchemaInterface<Array<SchemaInterface<unknown, unknown>>>
 
@@ -206,6 +211,10 @@ const booleanValidation = (value: unknown): value is boolean =>
 const dateValidation = (value: unknown): value is Date =>
   value instanceof Date && !Number.isNaN(value.getTime());
 
+// eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+const functionValidation = (value: unknown): value is Function =>
+  typeof value === 'function';
+
 const arrayValidation = (value: unknown): value is unknown[] =>
   Array.isArray(value);
 
@@ -385,6 +394,27 @@ export const s = {
       type: 'date',
     }) as DateSchemaInterface;
   },
+  /**
+   * Creates a function schema that validates the value is callable.
+   *
+   * @param options - Optional configuration (name, message)
+   * @returns Function schema interface
+   *
+   * @example
+   * ```typescript
+   * const callbackSchema = s.function();
+   * callbackSchema.parse(() => {}); // () => {}
+   * callbackSchema.parse('hello');  // throws
+   * ```
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+  function(options?: SchemaInterfaceOptions): FunctionSchemaInterface {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-function-type
+    return createSchemaInterface<Function, Function>(functionValidation, {
+      ...options,
+      type: 'function',
+    }) as FunctionSchemaInterface;
+  },
   /**
    * Creates an enum schema with predefined values.
    *