Add vitepress docs

docs/store/basic.md

@@ -0,0 +1,60 @@
+# Basic Utilities
+
+## synced
+Creates a writable store that automatically synchronizes its value with localStorage.
+
+```typescript
+const myStore = synced('storage-key', 'default value');
+```
+
+## getter
+Creates a function that returns the current value of a store without subscribing to it.
+
+```typescript
+const myStore = writable('value');
+const getValue = getter(myStore);
+
+```
+
+## withGetter
+Enhances a store by adding a getter method to access its current value.
+
+```typescript
+const myStore = withGetter(writable('value'));
+console.log(myStore.get()); // 'value'
+```
+
+## throttled
+Creates a store that limits how often subscribers receive updates.
+
+```typescript
+const throttledStore = throttled(1000, myStore); // Updates at most once per second
+```
+
+## custom
+Creates a custom store with optional throttling and custom set behavior.
+
+```typescript
+const customStore = custom(
+  set => {
+    // Setup logic
+    return () => {
+      // Cleanup logic
+    };
+  },
+  { throttle: 1000 }
+);
+```
+
+## adapter
+Creates a derived store that can transform values between two types while maintaining two-way binding.
+
+```typescript
+const adaptedStore = adapter({
+  store: originalStore,
+  forward: (source) => /* transform to target */,
+  backward: (target) => /* transform back to source */
+});
+```
+
+This is particularly useful when you need to transform data structures while maintaining the ability to update the original store.

docs/store/events.md

@@ -0,0 +1,122 @@
+# Event-Based Stores
+
+## deriveEventsMapped
+Creates a store that maintains a mapped collection of events from a repository.
+Useful when you want to transform events into a different data structure while maintaining reactivity.
+
+```typescript
+import {Repository, NAMED_PEOPLE, type TrustedEvent} from '@welshman/util'
+import {deriveEventsMapped} from '@welshman/store'
+
+interface UserProfile {
+  name: string;
+  about: string;
+  pubkey: string;
+}
+
+const repository = new Repository()
+
+const profiles = deriveEventsMapped<UserProfile>(repository, {
+  filters: [{kinds: [PROFILE]}],
+  eventToItem: (event: TrustedEvent) => ({
+    name: event.content.name,
+    about: event.content.about,
+    pubkey: event.pubkey,
+  }),
+  itemToEvent: (profile: UserProfile) => ({
+    // Convert profile back to event format
+    kind: PROFILE,
+    pubkey: profile.pubkey,
+    content: {
+      name: profile.name,
+      about: profile.about,
+    }
+  }),
+  throttle: 1000, // Optional: throttle updates
+  includeDeleted: false // Optional: exclude deleted events
+})
+```
+
+## deriveEvents
+Creates a store that maintains a collection of raw events from a repository.
+Useful when you want to work directly with events without transformation.
+
+```typescript
+import {Repository} from '@welshman/util'
+import {deriveEvents} from '@welshman/store'
+
+const repository = new Repository()
+
+const textNotes = deriveEvents(repository, {
+  filters: [{kinds: [NOTE], // kind 1 = text note
+  authors: ['pubkey1', 'pubkey2']}],
+  throttle: 500,
+  includeDeleted: false
+})
+
+// Subscribe to changes
+textNotes.subscribe(events => {
+  console.log('New text notes:', events)
+})
+```
+
+## deriveEvent
+Creates a store that tracks a single event by its ID or address.
+Returns a derived store containing the event or undefined.
+
+```typescript
+import {Repository} from '@welshman/util'
+import {deriveEvent} from '@welshman/store'
+
+const repository = new Repository()
+
+const specificEvent = deriveEvent(repository, 'event_id_or_address')
+
+// Subscribe to changes of the specific event
+specificEvent.subscribe(event => {
+  if (event) {
+    console.log('Event updated:', event)
+  } else {
+    console.log('Event not found')
+  }
+})
+```
+
+## deriveIsDeleted
+Creates a store that tracks whether an event has been deleted. Returns a boolean store.
+
+```typescript
+import {Repository} from '@welshman/util'
+import {deriveIsDeleted} from '@welshman/store'
+
+const repository = new Repository()
+const event = /* your event */
+
+const isDeleted = deriveIsDeleted(repository, event)
+
+// Subscribe to deletion status changes
+isDeleted.subscribe(deleted => {
+  console.log('Event deleted status:', deleted)
+})
+```
+
+## deriveIsDeletedByAddress
+Creates a store that tracks whether an event has been deleted by address.
+Similar to deriveIsDeleted but checks deletion by address instead of event ID.
+
+```typescript
+import {Repository} from '@welshman/util'
+import {deriveIsDeletedByAddress} from '@welshman/store'
+
+const repository = new Repository()
+const event = /* your event */
+
+const isDeletedByAddress = deriveIsDeletedByAddress(repository, event)
+
+// Subscribe to address-based deletion status changes
+isDeletedByAddress.subscribe(deleted => {
+  if (deleted) {
+    console.log('Event has been deleted by address')
+  }
+})
+```

docs/store/index.md

@@ -0,0 +1,18 @@
+# @welshman/store
+
+A utility package designed specifically for Svelte applications, providing enhanced store functionality and utilities for managing state. While it's primarily built for use with Svelte's store system, the concepts could be valuable for developers familiar with reactive programming patterns like RxJS.
+
+## What's Included
+
+- **Basic Utilities** - Enhanced stores with persistence, throttling, and getter methods
+- **Event-Based Stores** - Specialized stores for working with nostr events and repositories
+- **Custom Adapters** - Two-way data transformation with maintained reactivity
+- **Persistence Layer** - Automatic localStorage synchronization
+- **Performance Optimizations** - Throttled updates and efficient subscription management
+
+
+## Installation
+
+```bash
+npm install @welshman/store
+```