mcpbeat

Typed Service Contracts

google-labs-code/typed-service-contracts

Architecture standard for building robust, type-safe TypeScript services using the "Spec and Handler" pattern. Use when building CLIs, libraries, or complex business logic.

1k tokens
context cost
the whole folder, loaded on every use
1
files
instructions only
0
copies elsewhere
how many repositories repackaged it
26943
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/google-labs-code/design.md --skill typed-service-contracts

The instruction itself

11 sections, as written by the author

Typed Service Contracts (Spec & Handler Pattern)

This skill defines a Vertical Slice Architecture backed by Design by Contract (DbC) principles. It treats application logic as rigorously defined Units of Work where inputs are parsed (not just validated) and errors are treated as values (Result Pattern) rather than exceptions.

When to use this skill

  • Building CLIs or Libraries: When you need strict boundaries between user input and system logic.
  • Complex Validation: When inputs require transformation (parsing) before being useful (e.g., ensuring a string is a valid file path).
  • High-Reliability Requirements: When you cannot afford unhandled runtime exceptions and need exhaustive error handling.
  • Testing Focus: When you want to separate data validation tests from business logic tests.

Architecture Components

1. The Spec (spec.ts)

The "Contract" or "Port". It defines the *What*. It must contain:

  • Input Schema: A Zod schema that parses raw input into a valid DTO.
  • Output Schema: A Zod schema defining the successful data structure.
  • Error Schema: A discriminated union of specific failure modes (not generic errors).
  • Result Type: A DiscriminatedUnion of Success | Failure.
  • Interface: The capability definition (e.g., interface ConfigureSpec).

2. The Handler (handler.ts)

The "Implementation" or "Adapter". It defines the *How*. It must:

  • Implement the Interface defined in the Spec.
  • Be an "Impure" class that handles side effects (File System, API calls).
  • NEVER throw exceptions. It must catch internal errors and map them to the Result type.

How to use it

Step 1: Define the Contract (spec.ts)

Follow this template to define the boundaries.

import { z } from 'zod';

// 1. VALIDATION HELPERS (Reusable Refinements)
export const SafePathSchema = z.string()
  .min(1)
  .refine(p => !p.includes('..'), "No traversal allowed");

// 2. INPUT (The Command) - "Parse, don't validate"
export const MyTaskInputSchema = z.object({
  path: SafePathSchema,
  force: z.boolean().default(false),
});
export type MyTaskInput = z.infer<typeof MyTaskInputSchema>;

// 3. ERROR CODES (Exhaustive)
export const MyTaskErrorCode = z.enum([
  'FILE_NOT_FOUND',
  'PERMISSION_DENIED', 
  'UNKNOWN_ERROR'
]);

// 4. RESULT (The Monad)
export const MyTaskSuccess = z.object({
  success: z.literal(true),
  data: z.string(), // The output payload
});

export const MyTaskFailure = z.object({
  success: z.literal(false),
  error: z.object({
    code: MyTaskErrorCode,
    message: z.string(),
    suggestion: z.string().optional(),
    recoverable: z.boolean(),
  })
});

export type MyTaskResult = 
  | z.infer<typeof MyTaskSuccess> 
  | z.infer<typeof MyTaskFailure>;

// 5. INTERFACE (The Capability)
export interface MyTaskSpec {
  execute(input: MyTaskInput): Promise<MyTaskResult>;
}

Step 2: Implement the Handler (handler.ts)

Follow this template to implement the logic.

import { MyTaskSpec, MyTaskInput, MyTaskResult } from './spec.js';
import * as fs from 'fs';

export class MyTaskHandler implements MyTaskSpec {
  async execute(input: MyTaskInput): Promise<MyTaskResult> {
    try {
      // 1. Business Logic
      if (!fs.existsSync(input.path)) {
        // 2. Explicit Error Return (No Throwing)
        return {
          success: false,
          error: {
            code: 'FILE_NOT_FOUND',
            message: `Path does not exist: ${input.path}`,
            recoverable: true
          }
        };
      }

      // 3. Success Return
      return {
        success: true,
        data: 'Operation complete'
      };

    } catch (error) {
      // 4. Safety Net: Catch unknown runtime errors
      return {
        success: false,
        error: {
          code: 'UNKNOWN_ERROR',
          message: error instanceof Error ? error.message : String(error),
          recoverable: false
        }
      };
    }
  }
}

Step 3: Testing Strategy

Do not write monolithic tests. Split them into Contract Tests and Logic Tests.

A. Contract Tests (Schema)

Test the *Bouncer*. Ensure invalid data is rejected before it reaches the handler.

  • Focus: Edge cases, validation rules, Zod refinements.
  • Style: Data-driven (Table tests).
// spec.test.ts
import { MyTaskInputSchema } from './spec';

const invalidCases = [
  { val: '../etc/passwd', err: 'No traversal allowed' },
  { val: '', err: 'min(1)' },
];

test.each(invalidCases)('validates paths', ({ val, err }) => {
  const result = MyTaskInputSchema.safeParse({ path: val });
  expect(result.success).toBe(false);
});
B. Logic Tests (Handler)

Test the *Chef*. Mock external dependencies (fs, network) and assert the Result Object.

  • Focus: Business logic flow, error mapping, success states.
  • Style: Mocked unit tests or Scenario Runners.
// handler.test.ts
import { MyTaskHandler } from './handler';
import { vi } from 'vitest'; // or jest

test('returns FILE_NOT_FOUND if path missing', async () => {
  // MOCK
  vi.mocked(fs.existsSync).mockReturnValue(false);
  
  // EXECUTE
  const handler = new MyTaskHandler();
  const result = await handler.execute({ path: '/fake' });

  // ASSERT (Check the Result Object)
  expect(result.success).toBe(false);
  if (!result.success) {
    expect(result.error.code).toBe('FILE_NOT_FOUND');
  }
});

How to use it

Copy the folder

Take google-labs-code/typed-service-contracts from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.