95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
# @welshman/app
|
|
|
|
[](https://npmjs.com/package/@welshman/app)
|
|
|
|
An instance-based, composable client for building nostr applications. It powers production clients like [Coracle](https://coracle.social) and [Flotilla](https://flotilla.social), and ties together the rest of the welshman packages (`util`, `net`, `store`, `router`, `signer`, `feeds`) into a single, cohesive app layer.
|
|
|
|
## The core idea: an app is an `App` instance
|
|
|
|
Everything in `@welshman/app` hangs off a single `App` instance. An `App` owns the per-identity primitives — an event `Repository`, a connection `Pool`, a `Tracker`, and a `WrapManager` — plus a `config` and (optionally) a signed-in `User`. Because all state lives on the instance, two apps never share data: you can run multiple identities side-by-side, and tearing one down with `cleanup()` releases everything it allocated.
|
|
|
|
```typescript
|
|
import {createApp} from "@welshman/app"
|
|
|
|
// A batteries-included app (event ingestion, relay stats, gift-wrap
|
|
// unwrapping, and NIP-42 auth are all wired up by default policies)
|
|
const app = createApp()
|
|
```
|
|
|
|
Features are exposed as **plugins** — lazily-constructed singletons resolved through `app.use(...)`:
|
|
|
|
```typescript
|
|
import {createApp, Profiles, RelayLists, Thunks} from "@welshman/app"
|
|
|
|
const app = createApp()
|
|
|
|
// Each plugin is constructed once per app and memoized
|
|
const profiles = app.use(Profiles)
|
|
const relayLists = app.use(RelayLists)
|
|
```
|
|
|
|
This replaces the previous global-singleton design (`pubkey`, `deriveProfile`, `publishThunk`, `Router.get()`). There are no module-level globals anymore — you create an app and reach everything through it.
|
|
|
|
## Architecture at a glance
|
|
|
|
| Layer | What it is | Where |
|
|
|---|---|---|
|
|
| **`App`** | The app instance; owns repository/pool/tracker/wrapManager and the `use()` registry | [App](./app) |
|
|
| **`User` & sessions** | The signed-in identity and serializable login descriptors | [User & Sessions](./user) |
|
|
| **Policies** | Side effects installed at construction (ingest, auth, stats, wraps) | [App](./apppolicies) |
|
|
| **Plugins** | Lazily-resolved feature modules built on a small set of base classes | [Plugin architecture](./plugins) |
|
|
| **Data plugins** | Reactive collections of profiles, lists, relays, handles, zappers… | [Data](./data) |
|
|
| **Publishing** | Optimistic publishing via thunks | [Publishing](./publishing) |
|
|
| **Requests** | Loading & negentropy sync | [Requests](./requests) |
|
|
| **Routing** | Outbox-model relay selection and tag builders | [Routing](./routing) |
|
|
| **Web of Trust** | Follow/mute graph scoring | [Web of Trust](./wot) |
|
|
| **Feeds & Search** | Feed controllers and fuzzy search | [Feeds & Search](./feeds-and-search) |
|
|
|
|
## Quick example
|
|
|
|
```typescript
|
|
import {createApp, User, toSession, nip07, Profiles, Thunks, Router} from "@welshman/app"
|
|
import {getNip07} from "@welshman/signer"
|
|
import {makeEvent, NOTE} from "@welshman/util"
|
|
import {addMinimalFallbacks} from "@welshman/router"
|
|
|
|
// 1. Log in. A session is a serializable {method, data} descriptor; User
|
|
// turns it back into a live, signing identity.
|
|
const pubkey = await getNip07().getPubkey()
|
|
const session = toSession(nip07, {})
|
|
const user = await User.fromSession(session)
|
|
|
|
// 2. Create the app around that user.
|
|
const app = createApp({user})
|
|
|
|
// 3. Read data reactively. Stores lazily fetch over the network using the
|
|
// outbox model and update as events arrive.
|
|
const profile = app.use(Profiles).one(pubkey) // Readable<Maybe<Profile>>
|
|
profile.subscribe($profile => console.log($profile?.name))
|
|
|
|
// 4. Publish optimistically. The event is written to the local repository
|
|
// immediately, signed lazily, and progress is reported per-relay.
|
|
const thunk = app.use(Thunks).publishToOutbox({
|
|
event: makeEvent(NOTE, {content: "hi"}),
|
|
delay: 3000, // soft-undo window
|
|
})
|
|
|
|
// Abort before `delay` elapses to undo
|
|
// thunk.abort()
|
|
await thunk.waitForCompletion()
|
|
|
|
// 5. Tear it all down
|
|
app.cleanup()
|
|
```
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install @welshman/app
|
|
# or
|
|
pnpm add @welshman/app
|
|
yarn add @welshman/app
|
|
```
|
|
|
|
`@welshman/app` has peer dependencies on `svelte` (4 or 5) and the other welshman workspace packages (`@welshman/feeds`, `@welshman/lib`, `@welshman/net`, `@welshman/router`, `@welshman/signer`, `@welshman/store`, `@welshman/util`), plus `@pomade/core` for the optional Pomade signer.
|