Agent skill
hono-ipc-patterns
Advanced patterns for Hono-based Electron IPC including CQRS, Zod validation, error handling, and reactive data with RxJS. Use when implementing complex IPC patterns or needing guidance on architecture decisions.
Stars
163
Forks
31
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/hono-ipc-patterns
SKILL.md
Hono IPC Patterns
This skill provides advanced patterns for building robust IPC communication in Electron applications using Hono.
When This Skill Applies
- Implementing CQRS (Command Query Responsibility Segregation) pattern
- Adding Zod validation to routes
- Handling errors with Result types (neverthrow)
- Implementing reactive data streams with RxJS
- Testing IPC routes
CQRS Pattern
Core Principles
| Aspect | Query | Command |
|---|---|---|
| Purpose | Read data | Modify state |
| Return Type | Observable<T> |
ResultAsync<void, Error> |
| Side Effects | None | Database/API writes |
| Caching | Yes (reactive updates) | No |
Service Interface Example
typescript
// src/shared/services/event.service.ts
import type { Observable } from 'rxjs';
import type { ResultAsync } from 'neverthrow';
export interface EventService {
// === QUERIES (return Observable) ===
// Get active event (reactive - auto-updates on changes)
active(): Observable<EventInstance | undefined>;
// Get event history (reactive)
histories(includeHidden?: boolean): Observable<EventInstance[]>;
// Get single event
get(id: number): Observable<EventInstance | undefined>;
// === COMMANDS (return ResultAsync) ===
// Create event (one-shot operation)
create(data: CreateEventData): ResultAsync<void, ApplicationError>;
// Update event
update(id: number, data: UpdateEventData): ResultAsync<void, ApplicationError>;
// Delete event
delete(id: number): ResultAsync<void, ApplicationError>;
// Perform action on event
invite(userId: string, location: Location): ResultAsync<void, ApplicationError>;
}
Route Handler Pattern
typescript
// For Queries - convert Observable to single value
.get('/', async (c) => {
const result = await firstValueFrom(c.var.services.events.histories());
return c.json(result, 200);
})
// For Commands - use Result pattern matching
.post('/', zValidator('json', CreateEventBody), async (c) => {
const body = c.req.valid('json');
const result = await c.var.services.events.create(body);
return result.match(
() => c.json({ success: true }, 201),
(error) => c.json({ error: error.message }, error.statusCode ?? 500)
);
})
See CQRS.md for complete CQRS documentation.
Zod Validation Patterns
Request Validation Layers
typescript
import { zValidator } from '@hono/zod-validator';
import { z } from 'zod';
// Path parameter validation
const IdParam = z.object({
id: z.string().regex(/^[a-z]{3}_[a-zA-Z0-9]+$/),
});
// Query parameter validation (with coercion)
const PaginationQuery = z.object({
limit: z.coerce.number().int().positive().max(100).default(10),
offset: z.coerce.number().int().nonnegative().default(0),
});
// JSON body validation
const CreateBody = z.object({
name: z.string().min(1).max(100),
description: z.string().max(1000).optional(),
});
// Combined usage
.get('/:id', zValidator('param', IdParam), (c) => { ... })
.get('/', zValidator('query', PaginationQuery), (c) => { ... })
.post('/', zValidator('json', CreateBody), (c) => { ... })
See ZOD-VALIDATION.md for complete validation documentation.
Error Handling Patterns
Centralized Error Handler
typescript
const factory = (deps: Dependencies) =>
createFactory<HonoEnv>({
initApp(app) {
// Global error handler
app.onError((err, c) => {
// Log error
deps.logger?.error('Request error:', err);
// Handle known error types
if (err instanceof HTTPException) {
return c.json({ error: err.message }, err.status);
}
if (err instanceof ValidationError) {
return c.json({ error: err.message, details: err.issues }, 400);
}
// Unknown errors
return c.json({ error: 'Internal Server Error' }, 500);
});
},
});
Result Type Pattern Matching
typescript
.post('/action', async (c) => {
const result = await c.var.services.action.perform();
return result.match(
(data) => c.json(data, 200),
(error) => {
// Type-safe error handling
switch (error.code) {
case 'NOT_FOUND':
return c.json({ error: error.message }, 404);
case 'UNAUTHORIZED':
return c.json({ error: error.message }, 401);
case 'VALIDATION_ERROR':
return c.json({ error: error.message, details: error.details }, 400);
default:
return c.json({ error: 'Operation failed' }, 500);
}
}
);
})
Reactive Data Patterns
BehaviorSubject for Query Updates
typescript
// Service implementation pattern
export class UserServiceImpl implements UserService {
#notify = new BehaviorSubject(Date.now());
// Query: Returns Observable that updates on changes
list(): Observable<User[]> {
return concat(
// Initial data fetch
from(this.#fetchUsers()),
// Re-fetch when notified
this.#notify.pipe(
distinctUntilChanged(),
mergeMap(() => this.#fetchUsers())
)
);
}
// Command: Modifies data and notifies subscribers
async create(data: CreateUserData): ResultAsync<void, Error> {
const result = await this.#createUser(data);
if (result.isOk()) {
// Notify all query subscribers to refresh
this.#notify.next(Date.now());
}
return result;
}
}
Helper for Observable to Value
typescript
// utils/observable.ts
import { firstValueFrom, Observable } from 'rxjs';
export const firstValueFromResult = <T>(
observable: Observable<T>
): Promise<T> => {
return firstValueFrom(observable);
};
// Usage in routes
.get('/', async (c) => {
const users = await firstValueFromResult(c.var.services.users.list());
return c.json(users, 200);
})
Testing Patterns
Route Unit Testing
typescript
import { Hono } from 'hono';
import { beforeEach, describe, expect, it, vi } from 'vitest';
import { of } from 'rxjs';
import { ok, err } from 'neverthrow';
describe('Events Route', () => {
let app: Hono<HonoEnv>;
let mockEventService: Partial<EventService>;
beforeEach(() => {
mockEventService = {
list: vi.fn(),
create: vi.fn(),
};
app = new Hono<HonoEnv>();
app.use((c, next) => {
c.set('services', { events: mockEventService } as any);
return next();
});
app.route('/events', routes);
});
it('should list events', async () => {
mockEventService.list.mockReturnValue(of([{ id: 1, name: 'Event' }]));
const res = await app.request('/events');
const data = await res.json();
expect(res.status).toBe(200);
expect(data).toHaveLength(1);
});
it('should handle create error', async () => {
mockEventService.create.mockReturnValue(
err({ code: 'VALIDATION_ERROR', message: 'Invalid data' })
);
const res = await app.request('/events', {
method: 'POST',
body: JSON.stringify({ name: '' }),
headers: { 'Content-Type': 'application/json' },
});
expect(res.status).toBe(400);
});
});
Files Reference
- CQRS.md - Complete CQRS pattern documentation
- ZOD-VALIDATION.md - Zod validation patterns
Didn't find tool you were looking for?