applesauce-core 1.0.0 → 2.0.0

package/README.md

@@ -1,13 +1,12 @@
 # applesauce-core
 
-AppleSauce is a collection of utilities for building reactive nostr applications. The core package provides an in-memory event database and reactive queries to help you build nostr UIs with less code.
+AppleSauce is a collection of utilities for building reactive nostr applications. The core package provides an in-memory event database and reactive models to help you build nostr UIs with less code.
 
 ## Key Components
 
 - **Helpers**: Core utility methods for parsing and extracting data from nostr events
 - **EventStore**: In-memory database for storing and subscribing to nostr events
-- **QueryStore**: Manages queries and ensures efficient subscription handling
-- **Queries**: Complex subscriptions for common nostr data patterns
+- **Models**: Complex subscriptions for common nostr data patterns
 
 ## Documentation
 
@@ -19,15 +18,13 @@ For detailed documentation and guides, visit:
 ## Example
 
 ```js
-import { EventStore, QueryStore } from "applesauce-core";
+import { EventStore } from "applesauce-core";
+import { ProfileModel, TimelineModel } from "applesauce-core/models";
 import { Relay } from "nostr-tools/relay";
 
 // Create a single EventStore instance for your app
 const eventStore = new EventStore();
 
-// Create a QueryStore to manage subscriptions efficiently
-const queryStore = new QueryStore(eventStore);
-
 // Use any nostr library for relay connections (nostr-tools, ndk, nostrify, etc...)
 const relay = await Relay.connect("wss://relay.example.com");
 
@@ -38,18 +35,15 @@ const sub = relay.subscribe([{ authors: ["3bf0c63fcb93463407af97a5e5ee64fa883d10
   },
 });
 
-// Subscribe to profile changes using ProfileQuery
-const profile = queryStore.createQuery(
-  ProfileQuery,
-  "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d",
-);
+// Subscribe to profile changes using ProfileModel
+const profile = eventStore.model(ProfileModel, "3bf0c63fcb93463407af97a5e5ee64fa883d107ef9e558472c4eb9aaaefa459d");
 
 profile.subscribe((parsed) => {
   if (parsed) console.log(parsed);
 });
 
 // Subscribe to a timeline of events
-const timeline = queryStore.createQuery(TimelineQuery, { kinds: [1] });
+const timeline = eventStore.model(TimelineModel, { kinds: [1] });
 
 timeline.subscribe((events) => {
   console.log(events);

package/dist/event-store/{database.d.ts → event-set.d.ts}

@@ -1,11 +1,12 @@
 import { Filter, NostrEvent } from "nostr-tools";
 import { Subject } from "rxjs";
 import { LRU } from "../helpers/lru.js";
+import { IEventSet } from "./interface.js";
 /**
- * An in-memory database for nostr events
- * NOTE: does not handle replaceable events
+ * A set of nostr events that can be queried and subscribed to
+ * NOTE: does not handle replaceable events or any deletion logic
  */
-export declare class Database {
+export declare class EventSet implements IEventSet {
     protected log: import("debug").Debugger;
     /** Indexes */
     protected kinds: Map<number, Set<import("nostr-tools").Event>>;
@@ -17,50 +18,64 @@ export declare class Database {
     /** A sorted array of replaceable events by uid */
     protected replaceable: Map<string, import("nostr-tools").Event[]>;
     /** A stream of events inserted into the database */
-    inserted: Subject<import("nostr-tools").Event>;
+    insert$: Subject<import("nostr-tools").Event>;
     /** A stream of events that have been updated */
-    updated: Subject<import("nostr-tools").Event>;
+    update$: Subject<import("nostr-tools").Event>;
     /** A stream of events removed from the database */
-    removed: Subject<import("nostr-tools").Event>;
+    remove$: Subject<import("nostr-tools").Event>;
     /** A method thats called before a new event is inserted */
-    onBeforeInsert?: (event: NostrEvent) => void;
+    onBeforeInsert?: (event: NostrEvent) => boolean;
+    /** The number of events in the event set */
     get size(): number;
-    protected claims: WeakMap<import("nostr-tools").Event, any>;
-    /** Index helper methods */
-    protected getKindIndex(kind: number): Set<import("nostr-tools").Event>;
-    protected getAuthorsIndex(author: string): Set<import("nostr-tools").Event>;
-    protected getTagIndex(tagAndValue: string): Set<import("nostr-tools").Event>;
     /** Moves an event to the top of the LRU cache */
     touch(event: NostrEvent): void;
     /** Checks if the database contains an event without touching it */
     hasEvent(id: string): boolean;
     /** Gets a single event based on id */
     getEvent(id: string): NostrEvent | undefined;
-    /** Checks if the database contains a replaceable event without touching it */
-    hasReplaceable(kind: number, pubkey: string, d?: string): boolean;
-    /** Gets an array of replaceable events */
-    getReplaceable(kind: number, pubkey: string, d?: string): NostrEvent[] | undefined;
+    /** Checks if the event set has a replaceable event */
+    hasReplaceable(kind: number, pubkey: string, identifier?: string): boolean;
+    /** Gets the latest replaceable event */
+    getReplaceable(kind: number, pubkey: string, identifier?: string): NostrEvent | undefined;
+    /** Gets the history of a replaceable event */
+    getReplaceableHistory(kind: number, pubkey: string, identifier?: string): NostrEvent[] | undefined;
+    /** Gets all events that match the filters */
+    getByFilters(filters: Filter | Filter[]): Set<NostrEvent>;
+    /** Gets a timeline of events that match the filters */
+    getTimeline(filters: Filter | Filter[]): NostrEvent[];
     /** Inserts an event into the database and notifies all subscriptions */
-    addEvent(event: NostrEvent): NostrEvent;
+    add(event: NostrEvent): NostrEvent | null;
     /** Inserts and event into the database and notifies all subscriptions that the event has updated */
-    updateEvent(event: NostrEvent): NostrEvent;
+    update(event: NostrEvent): boolean;
     /** Removes an event from the database and notifies all subscriptions */
-    removeEvent(eventOrId: string | NostrEvent): boolean;
+    remove(eventOrId: string | NostrEvent): boolean;
+    /** A weak map of events that are claimed by other things */
+    protected claims: WeakMap<import("nostr-tools").Event, any>;
     /** Sets the claim on the event and touches it */
-    claimEvent(event: NostrEvent, claim: any): void;
+    claim(event: NostrEvent, claim: any): void;
     /** Checks if an event is claimed by anything */
     isClaimed(event: NostrEvent): boolean;
     /** Removes a claim from an event */
     removeClaim(event: NostrEvent, claim: any): void;
     /** Removes all claims on an event */
     clearClaim(event: NostrEvent): void;
+    /** Index helper methods */
+    protected getKindIndex(kind: number): Set<import("nostr-tools").Event>;
+    protected getAuthorsIndex(author: string): Set<import("nostr-tools").Event>;
+    protected getTagIndex(tagAndValue: string): Set<import("nostr-tools").Event>;
+    /** Iterates over all events by author */
     iterateAuthors(authors: Iterable<string>): Generator<NostrEvent>;
+    /** Iterates over all events by indexable tag and value */
     iterateTag(tag: string, values: Iterable<string>): Generator<NostrEvent>;
+    /** Iterates over all events by kind */
     iterateKinds(kinds: Iterable<number>): Generator<NostrEvent>;
+    /** Iterates over all events by time */
     iterateTime(since: number | undefined, until: number | undefined): Generator<NostrEvent>;
+    /** Iterates over all events by id */
     iterateIds(ids: Iterable<string>): Generator<NostrEvent>;
     /** Returns all events that match the filter */
     getEventsForFilter(filter: Filter): Set<NostrEvent>;
+    /** Returns all events that match the filters */
     getEventsForFilters(filters: Filter[]): Set<NostrEvent>;
     /** Remove the oldest events that are not claimed */
     prune(limit?: number): number;

package/dist/event-store/{database.js → event-set.js}

@@ -1,15 +1,15 @@
 import { binarySearch, insertEventIntoDescendingList } from "nostr-tools/utils";
 import { Subject } from "rxjs";
-import { getEventUID, getIndexableTags, createReplaceableAddress, isReplaceable } from "../helpers/event.js";
-import { INDEXABLE_TAGS } from "./common.js";
-import { logger } from "../logger.js";
+import { createReplaceableAddress, getEventUID, getIndexableTags, isReplaceable } from "../helpers/event.js";
 import { LRU } from "../helpers/lru.js";
+import { logger } from "../logger.js";
+import { INDEXABLE_TAGS } from "./common.js";
 /**
- * An in-memory database for nostr events
- * NOTE: does not handle replaceable events
+ * A set of nostr events that can be queried and subscribed to
+ * NOTE: does not handle replaceable events or any deletion logic
  */
-export class Database {
-    log = logger.extend("Database");
+export class EventSet {
+    log = logger.extend("EventSet");
     /** Indexes */
     kinds = new Map();
     authors = new Map();
@@ -20,45 +20,17 @@ export class Database {
     /** A sorted array of replaceable events by uid */
     replaceable = new Map();
     /** A stream of events inserted into the database */
-    inserted = new Subject();
+    insert$ = new Subject();
     /** A stream of events that have been updated */
-    updated = new Subject();
+    update$ = new Subject();
     /** A stream of events removed from the database */
-    removed = new Subject();
+    remove$ = new Subject();
     /** A method thats called before a new event is inserted */
     onBeforeInsert;
+    /** The number of events in the event set */
     get size() {
         return this.events.size;
     }
-    claims = new WeakMap();
-    /** Index helper methods */
-    getKindIndex(kind) {
-        if (!this.kinds.has(kind))
-            this.kinds.set(kind, new Set());
-        return this.kinds.get(kind);
-    }
-    getAuthorsIndex(author) {
-        if (!this.authors.has(author))
-            this.authors.set(author, new Set());
-        return this.authors.get(author);
-    }
-    getTagIndex(tagAndValue) {
-        if (!this.tags.has(tagAndValue)) {
-            // build new tag index from existing events
-            const events = new Set();
-            const ts = Date.now();
-            for (const event of this.events.values()) {
-                if (getIndexableTags(event).has(tagAndValue)) {
-                    events.add(event);
-                }
-            }
-            const took = Date.now() - ts;
-            if (took > 100)
-                this.log(`Built index ${tagAndValue} took ${took}ms`);
-            this.tags.set(tagAndValue, events);
-        }
-        return this.tags.get(tagAndValue);
-    }
     /** Moves an event to the top of the LRU cache */
     touch(event) {
         this.events.set(event.id, event);
@@ -71,33 +43,54 @@ export class Database {
     getEvent(id) {
         return this.events.get(id);
     }
-    /** Checks if the database contains a replaceable event without touching it */
-    hasReplaceable(kind, pubkey, d) {
-        const events = this.replaceable.get(createReplaceableAddress(kind, pubkey, d));
+    /** Checks if the event set has a replaceable event */
+    hasReplaceable(kind, pubkey, identifier) {
+        const events = this.replaceable.get(createReplaceableAddress(kind, pubkey, identifier));
         return !!events && events.length > 0;
     }
-    /** Gets an array of replaceable events */
-    getReplaceable(kind, pubkey, d) {
-        return this.replaceable.get(createReplaceableAddress(kind, pubkey, d));
+    /** Gets the latest replaceable event */
+    getReplaceable(kind, pubkey, identifier) {
+        const address = createReplaceableAddress(kind, pubkey, identifier);
+        const events = this.replaceable.get(address);
+        return events?.[0];
+    }
+    /** Gets the history of a replaceable event */
+    getReplaceableHistory(kind, pubkey, identifier) {
+        const address = createReplaceableAddress(kind, pubkey, identifier);
+        return this.replaceable.get(address);
+    }
+    /** Gets all events that match the filters */
+    getByFilters(filters) {
+        return this.getEventsForFilters(Array.isArray(filters) ? filters : [filters]);
+    }
+    /** Gets a timeline of events that match the filters */
+    getTimeline(filters) {
+        const timeline = [];
+        const events = this.getEventsForFilters(Array.isArray(filters) ? filters : [filters]);
+        for (const event of events)
+            insertEventIntoDescendingList(timeline, event);
+        return timeline;
     }
     /** Inserts an event into the database and notifies all subscriptions */
-    addEvent(event) {
+    add(event) {
         const id = event.id;
         const current = this.events.get(id);
         if (current)
             return current;
-        this.onBeforeInsert?.(event);
+        // Ignore events if before insert returns false
+        if (this.onBeforeInsert?.(event) === false)
+            return null;
         this.events.set(id, event);
         this.getKindIndex(event.kind).add(event);
         this.getAuthorsIndex(event.pubkey).add(event);
+        // Add the event to the tag indexes if they exist
         for (const tag of getIndexableTags(event)) {
-            if (this.tags.has(tag)) {
+            if (this.tags.has(tag))
                 this.getTagIndex(tag).add(event);
-            }
         }
-        // insert into time index
+        // Insert into time index
         insertEventIntoDescendingList(this.created_at, event);
-        // insert into replaceable index
+        // Insert into replaceable index
         if (isReplaceable(event.kind)) {
             const uid = getEventUID(event);
             let array = this.replaceable.get(uid);
@@ -109,17 +102,19 @@ export class Database {
             // insert the event into the sorted array
             insertEventIntoDescendingList(array, event);
         }
-        this.inserted.next(event);
+        // Notify subscribers that the event was inserted
+        this.insert$.next(event);
         return event;
     }
     /** Inserts and event into the database and notifies all subscriptions that the event has updated */
-    updateEvent(event) {
-        const inserted = this.addEvent(event);
-        this.updated.next(inserted);
-        return inserted;
+    update(event) {
+        const inserted = this.add(event);
+        if (inserted)
+            this.update$.next(inserted);
+        return inserted !== null;
     }
     /** Removes an event from the database and notifies all subscriptions */
-    removeEvent(eventOrId) {
+    remove(eventOrId) {
         let event = typeof eventOrId === "string" ? this.events.get(eventOrId) : eventOrId;
         if (!event)
             throw new Error("Missing event");
@@ -150,11 +145,13 @@ export class Database {
         // remove any claims this event has
         this.claims.delete(event);
         // notify subscribers this event was removed
-        this.removed.next(event);
+        this.remove$.next(event);
         return true;
     }
+    /** A weak map of events that are claimed by other things */
+    claims = new WeakMap();
     /** Sets the claim on the event and touches it */
-    claimEvent(event, claim) {
+    claim(event, claim) {
         if (!this.claims.has(event)) {
             this.claims.set(event, claim);
         }
@@ -175,6 +172,35 @@ export class Database {
     clearClaim(event) {
         this.claims.delete(event);
     }
+    /** Index helper methods */
+    getKindIndex(kind) {
+        if (!this.kinds.has(kind))
+            this.kinds.set(kind, new Set());
+        return this.kinds.get(kind);
+    }
+    getAuthorsIndex(author) {
+        if (!this.authors.has(author))
+            this.authors.set(author, new Set());
+        return this.authors.get(author);
+    }
+    getTagIndex(tagAndValue) {
+        if (!this.tags.has(tagAndValue)) {
+            // build new tag index from existing events
+            const events = new Set();
+            const ts = Date.now();
+            for (const event of this.events.values()) {
+                if (getIndexableTags(event).has(tagAndValue)) {
+                    events.add(event);
+                }
+            }
+            const took = Date.now() - ts;
+            if (took > 100)
+                this.log(`Built index ${tagAndValue} took ${took}ms`);
+            this.tags.set(tagAndValue, events);
+        }
+        return this.tags.get(tagAndValue);
+    }
+    /** Iterates over all events by author */
     *iterateAuthors(authors) {
         for (const author of authors) {
             const events = this.authors.get(author);
@@ -184,6 +210,7 @@ export class Database {
             }
         }
     }
+    /** Iterates over all events by indexable tag and value */
     *iterateTag(tag, values) {
         for (const value of values) {
             const events = this.getTagIndex(tag + ":" + value);
@@ -193,6 +220,7 @@ export class Database {
             }
         }
     }
+    /** Iterates over all events by kind */
     *iterateKinds(kinds) {
         for (const kind of kinds) {
             const events = this.kinds.get(kind);
@@ -202,6 +230,7 @@ export class Database {
             }
         }
     }
+    /** Iterates over all events by time */
     *iterateTime(since, until) {
         let untilIndex = 0;
         let sinceIndex = this.created_at.length - 1;
@@ -223,6 +252,7 @@ export class Database {
             yield this.created_at[i];
         }
     }
+    /** Iterates over all events by id */
     *iterateIds(ids) {
         for (const id of ids) {
             if (this.events.has(id))
@@ -286,6 +316,7 @@ export class Database {
         }
         return events;
     }
+    /** Returns all events that match the filters */
     getEventsForFilters(filters) {
         if (filters.length === 0)
             throw new Error("No Filters");
@@ -304,7 +335,7 @@ export class Database {
         while (cursor) {
             const event = cursor.value;
             if (!this.isClaimed(event)) {
-                this.removeEvent(event);
+                this.remove(event);
                 removed++;
                 if (removed >= limit)
                     break;

package/dist/event-store/event-store.d.ts

@@ -1,20 +1,25 @@
 import { Filter, NostrEvent } from "nostr-tools";
 import { Observable } from "rxjs";
-import { Database } from "./database.js";
-import { IEventStore } from "./interface.js";
+import { EventSet } from "./event-set.js";
+import { IEventStore, ModelConstructor } from "./interface.js";
+import { AddressPointer, EventPointer } from "nostr-tools/nip19";
+/** A symbol on an event that marks which event store its part of */
 export declare const EventStoreSymbol: unique symbol;
 export declare class EventStore implements IEventStore {
-    database: Database;
+    database: EventSet;
     /** Enable this to keep old versions of replaceable events */
     keepOldVersions: boolean;
-    /** A method used to verify new events before added them */
+    /**
+     * A method used to verify new events before added them
+     * @returns true if the event is valid, false if it should be ignored
+     */
     verifyEvent?: (event: NostrEvent) => boolean;
     /** A stream of new events added to the store */
-    inserts: Observable<NostrEvent>;
+    insert$: Observable<NostrEvent>;
     /** A stream of events that have been updated */
-    updates: Observable<NostrEvent>;
+    update$: Observable<NostrEvent>;
     /** A stream of events that have been removed */
-    removes: Observable<NostrEvent>;
+    remove$: Observable<NostrEvent>;
     constructor();
     protected deletedIds: Set<string>;
     protected deletedCoords: Map<string, number>;
@@ -23,31 +28,46 @@ export declare class EventStore implements IEventStore {
     /** Copies important metadata from and identical event to another */
     static mergeDuplicateEvent(source: NostrEvent, dest: NostrEvent): void;
     /**
-     * Adds an event to the database and update subscriptions
-     * @throws
+     * Adds an event to the store and update subscriptions
+     * @returns The existing event or the event that was added, if it was ignored returns null
      */
-    add(event: NostrEvent, fromRelay?: string): NostrEvent;
+    add(event: NostrEvent, fromRelay?: string): NostrEvent | null;
     /** Removes an event from the database and updates subscriptions */
     remove(event: string | NostrEvent): boolean;
+    /** Add an event to the store and notifies all subscribes it has updated */
+    update(event: NostrEvent): boolean;
     /** Removes any event that is not being used by a subscription */
     prune(max?: number): number;
-    /** Add an event to the store and notifies all subscribes it has updated */
-    update(event: NostrEvent): NostrEvent;
-    /** Get all events matching a filter */
-    getAll(filters: Filter | Filter[]): Set<NostrEvent>;
-    /** Check if the store has an event */
+    /** Check if the store has an event by id */
     hasEvent(id: string): boolean;
+    /** Get an event by id from the store */
     getEvent(id: string): NostrEvent | undefined;
     /** Check if the store has a replaceable event */
     hasReplaceable(kind: number, pubkey: string, d?: string): boolean;
     /** Gets the latest version of a replaceable event */
-    getReplaceable(kind: number, pubkey: string, d?: string): NostrEvent | undefined;
+    getReplaceable(kind: number, pubkey: string, identifier?: string): NostrEvent | undefined;
     /** Returns all versions of a replaceable event */
-    getReplaceableHistory(kind: number, pubkey: string, d?: string): NostrEvent[] | undefined;
+    getReplaceableHistory(kind: number, pubkey: string, identifier?: string): NostrEvent[] | undefined;
+    /** Get all events matching a filter */
+    getByFilters(filters: Filter | Filter[]): Set<NostrEvent>;
     /** Returns a timeline of events that match filters */
     getTimeline(filters: Filter | Filter[]): NostrEvent[];
+    /** Sets the claim on the event and touches it */
+    claim(event: NostrEvent, claim: any): void;
+    /** Checks if an event is claimed by anything */
+    isClaimed(event: NostrEvent): boolean;
+    /** Removes a claim from an event */
+    removeClaim(event: NostrEvent, claim: any): void;
+    /** Removes all claims on an event */
+    clearClaim(event: NostrEvent): void;
+    /** A directory of all active models */
+    protected models: Map<ModelConstructor<any, any[]>, Map<string, Observable<any>>>;
+    /** How long a model should be kept "warm" while nothing is subscribed to it */
+    modelKeepWarm: number;
+    /** Get or create a model on the event store */
+    model<T extends unknown, Args extends Array<any>>(constructor: ModelConstructor<T, Args>, ...args: Args): Observable<T>;
     /**
-     * Creates an observable that streams all events that match the filter and remains open
+     * Creates an observable that streams all events that match the filter
      * @param filters
      * @param [onlyNew=false] Only subscribe to new events
      */
@@ -56,18 +76,37 @@ export declare class EventStore implements IEventStore {
     removed(id: string): Observable<never>;
     /** Creates an observable that emits when event is updated */
     updated(event: string | NostrEvent): Observable<NostrEvent>;
-    /** Creates an observable that subscribes to a single event */
+    /** Creates a {@link EventModel} */
     event(id: string): Observable<NostrEvent | undefined>;
-    /** Creates an observable that subscribes to multiple events */
+    /** Creates a {@link ReplaceableModel} */
+    replaceable(kind: number, pubkey: string, identifier?: string): Observable<NostrEvent | undefined>;
+    /** Creates a {@link TimelineModel} */
+    timeline(filters: Filter | Filter[], includeOldVersion?: boolean): Observable<NostrEvent[]>;
+    /** Creates a {@link EventsModel} */
     events(ids: string[]): Observable<Record<string, NostrEvent>>;
-    /** Creates an observable that subscribes to the latest version of a replaceable event */
-    replaceable(kind: number, pubkey: string, d?: string): Observable<NostrEvent | undefined>;
-    /** Creates an observable that subscribes to the latest version of an array of replaceable events*/
+    /** Creates a {@link ReplaceableSetModel} */
     replaceableSet(pointers: {
         kind: number;
         pubkey: string;
         identifier?: string;
     }[]): Observable<Record<string, NostrEvent>>;
-    /** Creates an observable that updates with an array of sorted events */
-    timeline(filters: Filter | Filter[], keepOldVersions?: boolean): Observable<NostrEvent[]>;
+    /** Creates a {@link ProfileModel} */
+    profile(pubkey: string): Observable<import("../helpers/profile.js").ProfileContent | undefined>;
+    /** Creates a {@link ContactsModel} */
+    contacts(pubkey: string): Observable<import("nostr-tools/nip19").ProfilePointer[]>;
+    /** Creates a {@link MuteModel} */
+    mutes(pubkey: string): Observable<import("../helpers/mutes.js").Mutes | undefined>;
+    /** Creates a {@link ReactionsModel} */
+    reactions(event: NostrEvent): Observable<import("nostr-tools").Event[]>;
+    /** Creates a {@link MailboxesModel} */
+    mailboxes(pubkey: string): Observable<{
+        inboxes: string[];
+        outboxes: string[];
+    } | undefined>;
+    /** Creates a {@link UserBlossomServersModel} */
+    blossomServers(pubkey: string): Observable<URL[]>;
+    /** Creates a {@link ThreadModel} */
+    thread(root: string | EventPointer | AddressPointer): Observable<import("../models/thread.js").Thread>;
+    /** Creates a {@link CommentsModel} */
+    comments(event: NostrEvent): Observable<import("nostr-tools").Event[]>;
 }