@codepunter-labs/mock-core

Core primitives and utilities for building mock SDKs. This package provides the foundation for all @codepunter-labs/mock-* packages.

Installation

npm install @codepunter-labs/mock-core

Features

• MockError: Standardized error shapes for simulating API failures
• MockScenario: Define sequences of mock outcomes (success/failure patterns)
• SpyFactory: Type-safe spy creation for Jest and Vitest
• ValidationHelpers: Request validation to catch integration bugs early
• DelayHelpers: Simulate network latency for testing loading states
• WebhookHelpers: Build webhook payloads and signature placeholders

Usage

Error Simulation

import { MockErrors } from '@codepunter-labs/mock-core';

// Simulate API errors
auth.verifyIdToken.mockRejectedValue(
  MockErrors.unauthorized('Token has expired')
);

auth.createUser.mockRejectedValue(
  MockErrors.badRequest('Invalid email format')
);

Scenario Management

import { MockScenario } from '@codepunter-labs/mock-core';

// Define a sequence of outcomes
const scenario = new MockScenario()
  .success({ user: { id: '123' } })
  .failure(MockErrors.rateLimited('Too many requests'))
  .success({ user: { id: '456' } });

// Apply to a spy
spy.mockImplementation(() => scenario.next());

Validation

import { validateObject, ValidationRules } from '@codepunter-labs/mock-core';

const schema = {
  email: ValidationRules.email(true),
  age: ValidationRules.range(18, 120, true),
  name: ValidationRules.string(true),
};

const errors = validateObject(request, schema);
if (errors.length > 0) {
  throw new Error(errors.join(', '));
}

Delay Simulation

import { withDelay, randomDelay } from '@codepunter-labs/mock-core';

// Add fixed delay
const delayedFn = withDelay(apiCall, 200);

// Add random network jitter
const jitteryFn = withRandomDelay(apiCall, 50, 200);

Webhook Helpers

import { makeWebhookPayload, MOCK_WEBHOOK_SIGNATURE } from '@codepunter-labs/mock-core';

const payload = makeWebhookPayload('charge.success', {
  reference: 'ref-123',
  amount: 5000,
});

const signature = MOCK_WEBHOOK_SIGNATURE;

API Reference

MockErrors

Standard HTTP error factories:

• badRequest(message?, raw?) - 400
• unauthorized(message?, raw?) - 401
• forbidden(message?, raw?) - 403
• notFound(message?, raw?) - 404
• conflict(message?, raw?) - 409
• unprocessable(message?, raw?) - 422
• rateLimited(message?, raw?) - 429
• serverError(message?, raw?) - 500
• badGateway(message?, raw?) - 502
• serviceUnavailable(message?, raw?) - 503
• custom(statusCode, code, message, raw?) - Custom error

ValidationRules

Common validation rules:

• string(required?)
• number(required?)
• boolean(required?)
• array(required?)
• object(required?)
• email(required?)
• url(required?)
• phone(required?)
• range(min, max, required?)
• minLength(min, required?)
• maxLength(max, required?)
• enum(values, required?)

Delay Helpers

• delay(ms) - Delay execution
• withDelay(fn, delayMs) - Wrap with pre-delay
• withPostDelay(fn, delayMs) - Wrap with post-delay
• randomDelay(minMs, maxMs) - Random delay
• withRandomDelay(fn, minMs, maxMs) - Wrap with random delay

License

MIT