Add documentation

packages/net/README.md

@@ -2,21 +2,60 @@
 
 Utilities having to do with connection management and nostr messages.
 
-- `Connection` - the main api for dealing with relay connections
-- `ConnectionAuth` - tracks auth status for a connection
-- `ConnectionSender` - a send queue for connections
-- `ConnectionState` - tracks pending publishes and requests for a connection
-- `ConnectionStats` - tracks timing and error stats for a connection
-- `Context` - provides default values for configuring `ctx.net`
-- `Executor` - implements common nostr flows on a given `target`
-- `Pool` - a thin wrapper around `Map` which stores `Connection`s
-- `Publish` - utilities for publishing events
-- `Socket` - a wrapper around isomorphic-ws that handles json parsing/serialization
-- `Subscribe` - utilities for making requests against nostr relays
-- `Tracker` - tracks which relays a given event was seen on
+```typescript
+import {ctx, setContext} from '@welshman/lib'
+import {type TrustedEvent, createEvent, NOTE} from '@welshman/util'
+import {subscribe, publish, getDefaultNetContext} from '@welshman/net'
 
-Executor `target`s extend `Emitter`, and have a `send` method, a `cleanup` method, and a `connections` getter. They are intended to be passed to an `Executor` for use.
+// Sets up customizable event valdation, handlers, etc
+setContext(getDefaultNetContext())
 
-- `targets/Multi` allows you to compose multiple targets together.
-- `targets/Relay` takes a `Connection` and provides listeners for different verbs.
-- `targets/Relays` takes an array of `Connection`s and provides listeners for different verbs, merging all events into a single stream.
+// Send a subscription
+const sub = subscribe({
+  relays: ['wss://relay.example.com/'],
+  filters: [{kinds: [1], limit: 1}],
+  closeOnEose: true,
+  timeout: 10000,
+})
+
+sub.emitter.on(SubscriptionEvent.Event, (url: string, event: TrustedEvent) => {
+  console.log(url, event)
+  sub.close()
+})
+
+// Publish an event
+const pub = publish({
+  relays: ['wss://relay.example.com/'],
+  event: createEvent(NOTE, {content: 'hi'}),
+})
+
+pub.emitter.on('*', (status: PublishStatus, url: string) => {
+  console.log(status, url)
+})
+
+// The Tracker class can tell you which relays an event was read from or published to
+console.log(ctx.net.tracker.getRelays(event.id))
+```
+
+The main reason this module exists is to support different backends via Executor and different `target` classes. For example, to add a local relay that automatically gets used:
+
+```typescript
+import {setContext} from '@welshman/lib'
+import {LOCAL_RELAY_URL, Relay, Repository} from '@welshman/util'
+import {getDefaultNetContext, Multi, Local, Relays, Executor} from '@welshman/net'
+
+const repository = new Repository()
+
+const relay = new Relay(repository)
+
+setContext(getDefaultNetContext({
+  getExecutor: (relays: string[]) => {
+    return new Executor(
+      new Multi([
+        new Local(relay),
+        new Relays(remoteUrls.map(url => ctx.net.pool.get(url))),
+      ])
+    )
+  },
+}))
+```

packages/net/typedoc.json

@@ -0,0 +1,3 @@
+{
+  "entryPoints": ["src/index.ts"]
+}