Skip to content

Commit fbfaa6e

Browse files
vveerrggvveerrgg
committed
docs: add comprehensive JSDoc documentation and TypeDoc setup
- Added JSDoc comments to all source files - Set up TypeDoc with markdown plugin - Added documentation workflow - Updated README with badges and documentation info - Bump version to 0.2.5
1 parent ee43049 commit fbfaa6e

34 files changed

+3017
-114
lines changed

‎.github/workflows/documentation.yml

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Documentation
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
pull_request:
7+
branches: [ main ]
8+
9+
jobs:
10+
build:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v3
15+
16+
- name: Use Node.js
17+
uses: actions/setup-node@v3
18+
with:
19+
node-version: '18.x'
20+
cache: 'npm'
21+
22+
- name: Install dependencies
23+
run: npm ci
24+
25+
- name: Generate documentation
26+
run: npm run docs
27+
28+
- name: Deploy to GitHub Pages
29+
if: github.ref == 'refs/heads/main'
30+
uses: peaceiris/actions-gh-pages@v3
31+
with:
32+
github_token: ${{ secrets.GITHUB_TOKEN }}
33+
publish_dir: ./docs
34+
force_orphan: true
35+
user_name: 'github-actions[bot]'
36+
user_email: 'github-actions[bot]@users.noreply.github.com'
37+
commit_message: 'docs: update documentation'

‎README.md

Lines changed: 85 additions & 103 deletions
Original file line numberDiff line numberDiff line change
@@ -1,144 +1,126 @@
1-
# Nostr Websocket Utils
1+
# @humanjavaenterprises/nostr-websocket-utils
22

3-
[![npm version](https://img.shields.io/npm/v/nostr-websocket-utils.svg)](https://www.npmjs.com/package/nostr-websocket-utils)
4-
[![License](https://img.shields.io/npm/l/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
3+
[![npm version](https://img.shields.io/npm/v/@humanjavaenterprises/nostr-websocket-utils.svg)](https://www.npmjs.com/package/@humanjavaenterprises/nostr-websocket-utils)
4+
[![License](https://img.shields.io/npm/l/@humanjavaenterprises/nostr-websocket-utils.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/blob/main/LICENSE)
55
[![Build Status](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/CI/badge.svg)](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/actions)
6+
[![Documentation](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/workflows/Documentation/badge.svg)](https://humanjavaenterprises.github.io/nostr-websocket-utils/)
67
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org)
78
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg)](https://github.com/prettier/prettier)
89

9-
A TypeScript library providing WebSocket utilities for Nostr applications, focusing on robust connection handling, automatic reconnection, and channel-based messaging. This library has been streamlined to remove any DOM-related code, enhancing performance and maintainability.
10+
A TypeScript library for building Nostr protocol WebSocket clients and servers.
1011

1112
## Features
1213

13-
- 🔄 Automatic reconnection with configurable attempts
14-
- 💓 Heartbeat monitoring with configurable intervals
15-
- 📨 Message queueing during disconnections
16-
- 📢 Channel-based broadcasting with filtered subscriptions
17-
- 🔒 Type-safe message handling with required handlers
18-
- 📝 Built-in logging with Winston integration
19-
- 🛡️ Comprehensive error handling and validation
20-
- 🧪 100% test coverage with Jest
21-
- 📦 Zero DOM dependencies
22-
- 🔍 Full TypeScript type safety
14+
- 🚀 Full Nostr protocol support
15+
- 🔒 Secure WebSocket connections
16+
- ♥️ Heartbeat mechanism for connection health
17+
- 🔄 Automatic reconnection handling
18+
- 📝 Comprehensive logging
19+
- 🎯 Type-safe message handling
20+
- 📦 Easy to use API
2321

2422
## Installation
2523

2624
```bash
27-
npm install nostr-websocket-utils
25+
npm install @humanjavaenterprises/nostr-websocket-utils
2826
```
2927

30-
## Breaking Changes in v0.2.4
28+
## Quick Start
3129

32-
- 🆕 Added dedicated Nostr WebSocket server implementation
33-
- 📝 Enhanced TypeScript type definitions for Nostr messages
34-
- 🔄 Improved message handling with strict type checking
35-
- 🧪 Added comprehensive test suite for Nostr server
36-
- 🛡️ Strengthened type safety with `unknown` types
37-
- 🔌 Added support for Nostr EVENT and REQ messages
30+
### Creating a Nostr WebSocket Client
3831

39-
## Usage
32+
```typescript
33+
import { NostrWSClient } from '@humanjavaenterprises/nostr-websocket-utils';
34+
35+
const client = new NostrWSClient('wss://relay.example.com', {
36+
logger: console,
37+
heartbeatInterval: 30000,
38+
handlers: {
39+
message: async (msg) => console.log('Received:', msg),
40+
error: (err) => console.error('Error:', err),
41+
close: () => console.log('Connection closed')
42+
}
43+
});
44+
45+
await client.connect();
46+
```
4047

41-
### Nostr Server Example
48+
### Creating a Nostr WebSocket Server
4249

4350
```typescript
44-
import { NostrWSServer, createWSServer } from 'nostr-websocket-utils';
45-
import { NostrWSMessageType, NostrWSEvent } from 'nostr-websocket-utils/types/nostr';
51+
import { createNostrServer } from '@humanjavaenterprises/nostr-websocket-utils';
4652

47-
// Create Nostr WebSocket server
48-
const server = createWSServer({
49-
port: 8080,
50-
heartbeatInterval: 30000, // Optional: 30 seconds
53+
const server = await createNostrServer(8080, {
54+
logger: console,
55+
heartbeatInterval: 30000,
5156
handlers: {
52-
// Required: Handle incoming messages
53-
message: async (socket, message) => {
54-
switch (message[0]) {
55-
case NostrWSMessageType.EVENT:
56-
const event = message[1] as NostrWSEvent;
57-
// Handle Nostr event
58-
break;
59-
case NostrWSMessageType.REQ:
60-
const [_type, subscriptionId, filter] = message;
61-
// Handle subscription request
62-
break;
63-
}
64-
},
65-
// Optional: Handle errors
66-
error: (socket, error) => {
67-
console.error('WebSocket error:', error);
68-
},
69-
// Optional: Handle client disconnection
70-
close: (socket) => {
71-
console.info('Client disconnected');
57+
message: async (ws, msg) => {
58+
console.log('Received message:', msg);
59+
// Handle the message
7260
}
7361
}
7462
});
63+
```
64+
65+
## Documentation
66+
67+
Full API documentation is available in the [docs](./docs) directory. The documentation includes:
7568

76-
// Start listening
77-
server.listen();
69+
- Detailed API reference
70+
- Type definitions
71+
- Examples and usage patterns
72+
- Best practices
73+
74+
To generate the documentation locally:
75+
76+
```bash
77+
npm run docs
7878
```
7979

80-
### Types
80+
This will create a `docs` directory with the full API documentation.
81+
82+
## Examples
83+
84+
### Subscribe to a Channel
8185

8286
```typescript
83-
// Nostr Event Type
84-
interface NostrWSEvent {
85-
id: string;
86-
pubkey: string;
87-
created_at: number;
88-
kind: number;
89-
tags: string[][];
90-
content: string;
91-
sig: string;
92-
}
93-
94-
// Nostr Filter Type
95-
interface NostrWSFilter {
96-
ids?: string[];
97-
authors?: string[];
98-
kinds?: number[];
99-
'#e'?: string[];
100-
'#p'?: string[];
101-
since?: number;
102-
until?: number;
103-
limit?: number;
104-
}
105-
106-
// Message Types
107-
enum NostrWSMessageType {
108-
EVENT = 'EVENT',
109-
REQ = 'REQ',
110-
CLOSE = 'CLOSE',
111-
NOTICE = 'NOTICE',
112-
AUTH = 'AUTH',
113-
EOSE = 'EOSE'
114-
}
87+
client.subscribe('my-channel', {
88+
filter: {
89+
authors: ['pubkey1', 'pubkey2'],
90+
kinds: [1]
91+
}
92+
});
11593
```
11694

117-
## Advanced Configuration
118-
119-
### Server Options
95+
### Broadcast a Message
12096

12197
```typescript
122-
interface NostrWSServerOptions {
123-
port: number;
124-
heartbeatInterval?: number;
125-
maxPayloadSize?: number;
126-
cors?: {
127-
origin?: string | string[];
128-
methods?: string[];
129-
};
130-
handlers: {
131-
message: MessageHandler;
132-
error?: ErrorHandler;
133-
close?: CloseHandler;
134-
};
135-
}
98+
server.broadcast({
99+
type: 'EVENT',
100+
data: {
101+
content: 'Hello everyone!',
102+
kind: 1
103+
}
104+
});
136105
```
137106

138107
## Contributing
139108

140-
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
109+
Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
141110

142111
## License
143112

144113
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
114+
115+
## Related Projects
116+
117+
- [nostr-protocol](https://github.com/nostr-protocol/nostr)
118+
- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
119+
120+
## Support
121+
122+
If you have any questions or need help, please:
123+
124+
1. Check the [documentation](./docs)
125+
2. Open an [issue](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues)
126+
3. Join our [Discord community](https://discord.gg/your-discord)

‎docs/README.md

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
**nostr-websocket-utils v0.2.4**
2+
3+
***
4+
5+
# @humanjavaenterprises/nostr-websocket-utils
6+
7+
A TypeScript library for building Nostr protocol WebSocket clients and servers.
8+
9+
## Features
10+
11+
- 🚀 Full Nostr protocol support
12+
- 🔒 Secure WebSocket connections
13+
- ♥️ Heartbeat mechanism for connection health
14+
- 🔄 Automatic reconnection handling
15+
- 📝 Comprehensive logging
16+
- 🎯 Type-safe message handling
17+
- 📦 Easy to use API
18+
19+
## Installation
20+
21+
```bash
22+
npm install @humanjavaenterprises/nostr-websocket-utils
23+
```
24+
25+
## Quick Start
26+
27+
### Creating a Nostr WebSocket Client
28+
29+
```typescript
30+
import { NostrWSClient } from '@humanjavaenterprises/nostr-websocket-utils';
31+
32+
const client = new NostrWSClient('wss://relay.example.com', {
33+
logger: console,
34+
heartbeatInterval: 30000,
35+
handlers: {
36+
message: async (msg) => console.log('Received:', msg),
37+
error: (err) => console.error('Error:', err),
38+
close: () => console.log('Connection closed')
39+
}
40+
});
41+
42+
await client.connect();
43+
```
44+
45+
### Creating a Nostr WebSocket Server
46+
47+
```typescript
48+
import { createNostrServer } from '@humanjavaenterprises/nostr-websocket-utils';
49+
50+
const server = await createNostrServer(8080, {
51+
logger: console,
52+
heartbeatInterval: 30000,
53+
handlers: {
54+
message: async (ws, msg) => {
55+
console.log('Received message:', msg);
56+
// Handle the message
57+
}
58+
}
59+
});
60+
```
61+
62+
## Documentation
63+
64+
Full API documentation is available in the [docs](./docs) directory. The documentation includes:
65+
66+
- Detailed API reference
67+
- Type definitions
68+
- Examples and usage patterns
69+
- Best practices
70+
71+
To generate the documentation locally:
72+
73+
```bash
74+
npm run docs
75+
```
76+
77+
This will create a `docs` directory with the full API documentation.
78+
79+
## Examples
80+
81+
### Subscribe to a Channel
82+
83+
```typescript
84+
client.subscribe('my-channel', {
85+
filter: {
86+
authors: ['pubkey1', 'pubkey2'],
87+
kinds: [1]
88+
}
89+
});
90+
```
91+
92+
### Broadcast a Message
93+
94+
```typescript
95+
server.broadcast({
96+
type: 'EVENT',
97+
data: {
98+
content: 'Hello everyone!',
99+
kind: 1
100+
}
101+
});
102+
```
103+
104+
## Contributing
105+
106+
Contributions are welcome! Please read our [Contributing Guide](_media/CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
107+
108+
## License
109+
110+
This project is licensed under the MIT License - see the [LICENSE](_media/LICENSE) file for details.
111+
112+
## Related Projects
113+
114+
- [nostr-protocol](https://github.com/nostr-protocol/nostr)
115+
- [nostr-tools](https://github.com/nbd-wtf/nostr-tools)
116+
117+
## Support
118+
119+
If you have any questions or need help, please:
120+
121+
1. Check the [documentation](./docs)
122+
2. Open an [issue](https://github.com/HumanjavaEnterprises/nostr-websocket-utils/issues)
123+
3. Join our [Discord community](https://discord.gg/your-discord)

0 commit comments

Comments
 (0)