open-index/open-npm huggingface dataset:
npm package: @socketdocs/cli
Description: The command-line interface for **SocketDocs**. Use it to initialize, generate, and visualize your WebSocket API documentation.
Author: Nwankwo Samuel
Latest version: 0.1.1

# @socketdocs/cli

The command-line interface for **SocketDocs**. Use it to initialize, generate, and visualize your WebSocket API documentation.

## 📦 Installation

```bash
# Global installation (recommended for CLI use)
npm install -g @socketdocs/cli

# Local installation as devDependency
npm install -D @socketdocs/cli
```

## 🚀 Getting Started

Initialize SocketDocs in your project:

```bash
socketdocs init
```

This creates a `socketdocs.config.json` file where you can specify your contract entry point and other settings.

## 🛠️ Commands

### `socketdocs init`
Sets up the project configuration and a basic documentation structure.

### `socketdocs generate`
Scans your contract and generates a JSON specification file.

```bash
socketdocs generate --output ./docs/spec.json
```

### `socketdocs serve`
Launches a local development server with a UI to visualize your WebSocket API documentation in real-time.

```bash
socketdocs serve --spec ./docs/spec.json --port 4000
```

## 📄 Configuration

A typical `socketdocs.config.json`:

```json
{
  "entry": "./src/contract.ts",
  "output": "./docs/socketdocs.json",
  "title": "My Realtime API",
  "version": "1.0.0"
}
```

## ⚖️ License

MIT
npm package: @socketdocs/core
Description: The core engine for **SocketDocs**, an OpenAPI-style documentation and validation framework for WebSocket APIs.
Author: Nwankwo Samuel
Latest version: 0.1.1

# @socketdocs/core

The core engine for **SocketDocs**, an OpenAPI-style documentation and validation framework for WebSocket APIs.

## 🚀 Overview

SocketDocs brings order to the wild west of WebSocket APIs. It allows you to define a single, typed **Contract** for your events using [Zod](https://zod.dev), which then powers:
- **Automatic Validation**: Incoming and outgoing payloads are automatically checked against your schemas.
- **Auto-Generated Documentation**: Export your contract to a JSON specification that can be rendered in a UI.
- **Consistency**: One source of truth for both your server-side logic and your API documentation.

## 📦 Installation

```bash
npm install @socketdocs/core zod
```

## 🛠️ Key Concepts

### **The Contract**
The `Contract` is the heart of your API. It holds the metadata (name, version, description) and all the event definitions.

```typescript
import { createContract } from '@socketdocs/core';

const contract = createContract({
  name: 'Realtime Chat',
  version: '1.2.0',
  description: 'A professional chat API with room support.',
});
```

### **Namespaces**
Just like Socket.IO, SocketDocs supports namespaces. If you don't need multiple namespaces, use the `default` one.

```typescript
const chatNamespace = contract.namespace('chat');
const adminNamespace = contract.namespace('admin');
```

### **Events**
Events are defined with a name, a direction, and a payload schema.

```typescript
import { z } from 'zod';

chatNamespace.event({
  name: 'message',
  direction: 'bidirectional', // 'client_to_server', 'server_to_client', or 'bidirectional'
  summary: 'Send/Receive messages',
  description: 'Used to broadcast chat messages to everyone in the room.',
  payload: z.object({
    user: z.string().min(3).max(20),
    text: z.string().nonempty(),
    timestamp: z.number().default(() => Date.now()),
  }),
});
```

## 📜 Generating Specifications

You can export your entire contract as a JSON object, which follows the SocketDocs specification format.

```typescript
const spec = contract.generateSpec();
console.log(JSON.stringify(spec, null, 2));
```

## 🧩 Plugin System

SocketDocs is extensible. You can register plugins to hook into the event lifecycle (e.g., for logging, metrics, or custom transformations).

```typescript
contract.registerPlugin({
  onEvent(name, payload, namespace) {
    console.log(`[SocketDocs] Event "${name}" in "${namespace}" triggered.`);
  }
});
```

## ⚖️ License

MIT
npm package: @socketdocs/fastify
Description: The **Fastify** adapter for **SocketDocs**. Seamlessly integrate WebSocket validation and documentation into your Fastify applications.
Author: Nwankwo Samuel
Latest version: 0.1.1

# @socketdocs/fastify

The **Fastify** adapter for **SocketDocs**. Seamlessly integrate WebSocket validation and documentation into your Fastify applications.

## 📦 Installation

```bash
npm install @socketdocs/fastify @socketdocs/core fastify @fastify/websocket zod
```

## 🚀 Getting Started

1.  **Define your contract**:

```typescript
import { createContract } from '@socketdocs/core';
import { z } from 'zod';

const contract = createContract({ name: 'Fastify API', version: '1.0.0' });
contract.namespace('default').event({
  name: 'greet',
  direction: 'client_to_server',
  payload: z.object({ name: z.string() })
});
```

2.  **Attach the adapter to your Fastify instance**:

```typescript
import Fastify from 'fastify';
import websocket from '@fastify/websocket';
import { bindFastifyAdapter } from '@socketdocs/fastify';

const fastify = Fastify();
fastify.register(websocket);

// Handlers for the events defined in the contract
const handlers = {
  'default': {
    'greet': async ({ payload, connection }: any) => {
      console.log(`Hello, ${payload.name}!`);
    }
  }
};

fastify.ready((err) => {
  if (err) throw err;
  bindFastifyAdapter(fastify, contract, handlers);
});

fastify.listen({ port: 3000 });
```

## 🛠️ Features

- **Fastify Ecosystem Integration**: Works perfectly with `@fastify/websocket`.
- **Validation**: Every incoming message is validated against its Zod schema. Invalid messages are handled automatically.
- **Route-Level Documentation**: Links your Fastify routes with your WebSocket contract for unified documentation.
- **Async Handling**: Full support for async/await in your event handlers.

## ⚖️ License

MIT
npm package: @socketdocs/socket-io
Description: The **Socket.IO** adapter for **SocketDocs**. Automatically validate and document your Socket.IO events using your contract.
Author: Nwankwo Samuel
Latest version: 0.1.1

# @socketdocs/socket-io

The **Socket.IO** adapter for **SocketDocs**. Automatically validate and document your Socket.IO events using your contract.

## 📦 Installation

```bash
npm install @socketdocs/socket-io @socketdocs/core socket.io zod
```

## 🚀 Getting Started

1.  **Define your contract** (using `@socketdocs/core`):

```typescript
import { createContract } from '@socketdocs/core';
import { z } from 'zod';

const contract = createContract({ name: 'My API', version: '1.0.0' });
contract.namespace('default').event({
  name: 'hello',
  direction: 'client_to_server',
  payload: z.string()
});
```

2.  **Attach the adapter to your Socket.IO server**:

```typescript
import { Server } from 'socket.io';
import { bindSocketioAdapter } from '@socketdocs/socket-io';

const io = new Server(3000);

// Handlers for the events defined in the contract
const handlers = {
  'default': {
    'hello': async ({ payload, socket }: any) => {
      console.log(`Received: ${payload}`);
      return { status: 'ok' };
    }
  }
};

bindSocketioAdapter(io, contract, handlers);
```

## 🛠️ Features

- **Namespace Awareness**: Automatically maps contract namespaces to Socket.IO namespaces.
- **Validation**: Every incoming event is validated against its Zod schema. Invalid payloads are logged and optionally blocked.
- **Unified Handlers**: Use the `handlers` map for cleaner code structure, while still having access to the raw `socket` instance.
- **Emit with Validation**: The adapter provides an `emit` helper that validates outgoing payloads against the contract.

## ⚖️ License

MIT
npm package: @socketdocs/ws
Description: The **ws** library adapter for **SocketDocs**. Bring contract-driven validation and documentation to your raw WebSocket servers.
Author: Nwankwo Samuel
Latest version: 0.1.1

# @socketdocs/ws

The **ws** library adapter for **SocketDocs**. Bring contract-driven validation and documentation to your raw WebSocket servers.

## 📦 Installation

```bash
npm install @socketdocs/ws @socketdocs/core ws zod
```

## 🚀 Getting Started

1.  **Define your contract**:

```typescript
import { createContract } from '@socketdocs/core';
import { z } from 'zod';

const contract = createContract({ name: 'Raw WS API', version: '1.0.0' });
contract.namespace('default').event({
  name: 'ping',
  direction: 'client_to_server',
  payload: z.object({ id: z.string() })
});
```

2.  **Attach the adapter to your WebSocket server**:

```typescript
import { WebSocketServer } from 'ws';
import { bindWSAdapter } from '@socketdocs/ws';

const wss = new WebSocketServer({ port: 3000 });

// Handlers for the events defined in the contract
const handlers = {
  'default': {
    'ping': async ({ payload, socket }: any) => {
      console.log(`Ping received: ${payload.id}`);
      socket.send(JSON.stringify({ event: 'pong', payload: { id: payload.id } }));
    }
  }
};

bindWSAdapter(wss, contract, handlers);
```

## 🛠️ Features

- **JSON Protocol Support**: Automatically parses incoming messages and serializes outgoing ones, following a consistent `{ event: string, payload: any }` structure.
- **Validation**: Every incoming message is validated against its Zod schema. Invalid messages are ignored or generate errors.
- **Clean Event Handling**: Organize your WebSocket logic with a simple handler mapping.
- **Schema-First**: Leverage your existing `Contract` to ensure your raw WebSocket server stays in sync with its documentation.

## ⚖️ License

MIT