Core API
Parameters
Parameter types and validation
Parameters#
Parameters are validated automatically before your handler runs. Surf supports five types: string, number, boolean, object, and array.
typescript
{ params: { // Required string name: { type: 'string', required: true, description: 'User name' }, // String with enum constraint category: { type: 'string', enum: ['electronics', 'clothing', 'books'] }, // Number with default limit: { type: 'number', default: 10 }, // Boolean includeArchived: { type: 'boolean', default: false }, // Nested object shipping: { type: 'object', properties: { address: { type: 'string', required: true }, express: { type: 'boolean', default: false }, }, }, // Array with typed items tags: { type: 'array', items: { type: 'string' }, }, // Array with $ref items (reusable types) items: { type: 'array', items: { $ref: 'CartItem' }, }, },}You can define reusable types in the types config and reference them with $ref:
typescript
const surf = await createSurf({ name: 'My Store', types: { CartItem: { type: 'object', description: 'An item in the shopping cart', properties: { sku: { type: 'string', required: true }, quantity: { type: 'number', default: 1 }, }, }, }, commands: { 'cart.add': { description: 'Add items to cart', params: { items: { type: 'array', items: { $ref: 'CartItem' } }, }, run: async ({ items }) => { /* ... */ }, }, },})