@objectstack/plugin-msw

MSW (Mock Service Worker) Plugin for ObjectStack Runtime. This plugin enables seamless integration with Mock Service Worker for testing and development environments.

🤖 AI Development Context

Role: Test Mocking Adapter
Usage:
- Intercepts network requests in tests (Browser/Node).
- Simulates a real ObjectStack backend.

Plugin Capabilities

This plugin implements the ObjectStack plugin capability protocol:
- Protocol: com.objectstack.protocol.testing.mock.v1 (full conformance)
- Protocol: com.objectstack.protocol.api.rest.v1 (full conformance)
- Provides: ObjectStackServer interface for mock API operations
- Requires: com.objectstack.engine.objectql for data operations

See objectstack.config.ts for the complete capability manifest.

Features

- 🎯 Unified Dispatcher: Uses @objectstack/runtime's HttpDispatcher to ensure mocks behave exactly like the real server.
- 🔄 Full Protocol Support: Mocks all Runtime endpoints:
- Auth (/auth)
- Metadata (/metadata)
- Data (/data - with filtering, batching, relations)
- Storage (/storage)
- Analytics (/analytics)
- Automation (/automation)
- 🌐 Universal Support: Works in Browser (Service Worker) and Node.js (Interceptor).
- 🎨 Custom Handlers: Easily inject custom MSW handlers that take precedence.
- 📝 TypeScript First: Fully typed configuration.

Installation

``bash
pnpm add @objectstack/plugin-msw msw
`

Usage

$3

`typescript
import { MSWPlugin } from '@objectstack/plugin-msw';
import { ObjectKernel } from '@objectstack/runtime';

const kernel = new ObjectKernel();

// The MSW Plugin will initialize the HttpDispatcher and intercept requests
kernel.use(new MSWPlugin({
enableBrowser: true,
baseUrl: '/api/v1',
logRequests: true
}));

await kernel.start();
`

$3

The plugin uses the HttpDispatcher from the Runtime to process requests intercepted by MSW. This means your mock server runs the actual ObjectStack business logic (permissions, validation, flow execution) in-memory, providing a high-fidelity simulation of the backend.
}));

await kernel.bootstrap();
`

$3

`typescript
import { setupWorker } from 'msw/browser';
import { http, HttpResponse } from 'msw';
import { ObjectStackServer } from '@objectstack/plugin-msw';

// 1. Initialize the mock server
ObjectStackServer.init(protocol);

// 2. Define your handlers
const handlers = [
// Intercept GET /api/user/:id
http.get('/api/user/:id', async ({ params }) => {
const result = await ObjectStackServer.getData('user', params.id as string);
return HttpResponse.json(result.data, { status: result.status });
}),

// Intercept POST /api/user
http.post('/api/user', async ({ request }) => {
const body = await request.json();
const result = await ObjectStackServer.createData('user', body);
return HttpResponse.json(result.data, { status: result.status });
}),
];

// 3. Create and start the worker
const worker = setupWorker(...handlers);
await worker.start();
`

$3

`typescript
import { MSWPlugin } from '@objectstack/plugin-msw';
import { http, HttpResponse } from 'msw';

const customHandlers = [
http.get('/api/custom/:id', ({ params }) => {
return HttpResponse.json({ id: params.id, custom: true });
})
];

const plugin = new MSWPlugin({
customHandlers,
baseUrl: '/api/v1'
});
`

API Reference

$3

The main plugin class that implements the ObjectStack Runtime Plugin interface.

#### Options

`typescript
interface MSWPluginOptions {
/**
* Enable MSW in the browser environment
* @default true
*/
enableBrowser?: boolean;

/**
* Custom handlers to add to MSW
*/
customHandlers?: Array;

/**
* Base URL for API endpoints
* @default '/api/v1'
*/
baseUrl?: string;

/**
* Whether to log requests
* @default true
*/
logRequests?: boolean;
}
`

$3

The mock server that handles ObjectStack API calls.

#### Static Methods

- init(protocol, logger?) - Initialize the mock server with an ObjectStack protocol instance
- findData(object, params?) - Find records for an object
- getData(object, id) - Get a single record by ID
- createData(object, data) - Create a new record
- updateData(object, id, data) - Update an existing record
- deleteData(object, id) - Delete a record
- getUser(id) - Legacy method for getting user (alias for getData('user', id))
- createUser(data) - Legacy method for creating user (alias for createData('user', data))

Mocked Endpoints

The plugin automatically mocks the following ObjectStack API endpoints:

$3


- GET /api/v1 - Get API discovery information

$3

- GET /api/v1/meta - Get available metadata types
- GET /api/v1/meta/:type - Get metadata items for a type
- GET /api/v1/meta/:type/:name - Get specific metadata item

$3

- GET /api/v1/data/:object - Find records
- GET /api/v1/data/:object/:id - Get record by ID
- POST /api/v1/data/:object - Create record
- PATCH /api/v1/data/:object/:id - Update record
- DELETE /api/v1/data/:object/:id - Delete record

$3

- GET /api/v1/ui/view/:object - Get UI view configuration

Example: Testing with Vitest

`typescript
import { describe, it, expect, beforeAll, afterAll } from 'vitest';
import { setupWorker } from 'msw/browser';
import { ObjectStackServer } from '@objectstack/plugin-msw';
import { http, HttpResponse } from 'msw';

describe('User API', () => {
let worker: any;

beforeAll(async () => {
// Initialize mock server
ObjectStackServer.init(protocol);

// Setup handlers
const handlers = [
http.get('/api/user/:id', async ({ params }) => {
const result = await ObjectStackServer.getData('user', params.id as string);
return HttpResponse.json(result.data, { status: result.status });
})
];

worker = setupWorker(...handlers);
await worker.start({ onUnhandledRequest: 'bypass' });
});

afterAll(() => {
worker.stop();
});

it('should get user by id', async () => {
const response = await fetch('/api/user/123');
const data = await response.json();

expect(response.status).toBe(200);
expect(data).toBeDefined();
});
});
``

License

Apache-2.0

Related Packages

- @objectstack/runtime - ObjectStack Runtime
- @objectstack/spec - ObjectStack Specifications
- msw - Mock Service Worker